setup/README

   1 Initialising a dak database schema
   2 ==================================
   3
   4 The following packages are needed:
   5  * postgresql-9.0 postgresql-client-9.0 postgresql-plperl-9.0 postgresql-plpython-9.0 postgresql-9.0-debversion
   6
   7 (the schema assumes at least postgresql 9.0; ftpmaster in Debian currently uses
   8 the squeeze postgresql 9.0 backport)
   9
  10 The following roles are assumed to exist:
  11  * dak: database superuser: needs to be an actual user
  12  * ftpmaster: role which should be given to archive administrators
  13  * ftpteam: people who can do NEW processing, overrides, removals, etc
  14  * ftptrainee: people who can add notes to packages in NEW
  15
  16 For the purposes of this document, we'll be working in /srv/dak
  17
  18 Set up the dak user on both the system and in postgres:
  19 # sudo addgroup --system ftpmaster
  20 # sudo adduser --system dak --ingroup ftpmaster --shell /bin/bash
  21 # sudo -u postgres createuser -s dak
  22
  23 Set up the dak directory:
  24 # sudo mkdir /etc/dak
  25 # sudo mkdir /srv/dak
  26 # sudo chown dak:ftpmaster /srv/dak
  27 # sudo chmod 2775 /srv/dak
  28
  29 Create a symlink to /srv/dak/dak.conf in /etc/dak
  30 (we'll create the config file in a bit)
  31 # sudo ln -s /srv/dak/dak.conf /etc/dak/dak.conf
  32
  33 Become the dak user:
  34 # sudo -u dak -s -H
  35
  36 Create the additional roles:
  37 # createuser -S -R -D ftpmaster
  38 # createuser -S -R -D ftpteam
  39 # createuser -S -R -D ftptrainee
  40
  41 Create an empty database with SQL_ASCII encoding:
  42 # createdb -T template0 -E SQL_ASCII -O dak projectb
  43
  44 Import the schema:
  45 # psql -f current_schema.sql -d projectb
  46
  47 Set up some core data in projectb to get started (read the init_vars file if
  48 you wish to customise various aspects):
  49 # ./init_core
  50
  51 Create a minimal dak.conf
  52 # ./init_minimal_conf > /srv/dak/dak.conf
  53
  54 Set up a symlink somewhere
  55 # mkdir ~dak/bin
  56 # ln -s /path/to/dak.py ~dak/bin/dak
  57
  58 At this point, you should be able to test that the database schema is
  59 up-to-date
  60 # dak update-db
  61
  62 Run dak init-dirs to set up the initial /srv/dak tree
  63 # dak init-dirs
  64
  65 Copy the email templates into the /srv/dak tree.
  66 WARNING: Please check these templates over and customise as necessary
  67 # cp templates/* /srv/dak/templates/
  68
  69 Set up a private signing key: don't set a passphrase as dak will not
  70 pass one through to gpg.  Guard this key carefully!
  71 The key only needs to be able to sign, it doesn't need to be able
  72 to encrypt.
  73 # gpg --no-default-keyring --secret-keyring /srv/dak/keyrings/s3kr1t/dot-gnupg/secring.gpg --keyring /srv/dak/keyrings/s3kr1t/dot-gnupg/pubring.gpg --gen-key
  74 Remember the signing key id for when creating the suite below.
  75 Here we'll pretend it is DDDDDDDD for convenience
  76
  77 Import some developer keys.
  78 Either import from keyservers (here AAAAAAAA):
  79 # gpg --no-default-keyring --keyring /srv/dak/keyrings/upload-keyring.gpg --recv-key AAAAAAAA
  80 or import from files:
  81 # gpg --no-default-keyring --keyring /srv/dak/keyrings/upload-keyring.gpg --import /path/to/keyfile
  82
  83 Import the developer keys into the database
  84 The -U '%s' tells dak to add UIDs automatically
  85 # dak import-keyring -U '%s' /srv/dak/keyrings/upload-keyring.gpg
  86
  87 Add some architectures you care about:
  88 # dak admin architecture add i386 "Intel x86 port"
  89 # dak admin architecture add amd64 "AMD64 port"
  90
  91 Add a suite (origin=, label= and codename= are optional)
  92 signingkey= will ensure that Release files are signed
  93 # dak admin suite add-all-arches unstable x.y.z origin=MyDistro label=Master codename=sid signingkey=DDDDDDDD
  94
  95 Re-run dak init-dirs to add new suite directories to /srv/dak
  96 # dak init-dirs
  97
  98 #######################################################################
  99 # Example package flow
 100 #######################################################################
 101
 102 For this example, we've grabbed and built the hello source package
 103 for AMD64 and copied it into /srv/dak/queue/unchecked.
 104
 105 We start by performing initial package checks which will
 106 result in the package being moved to NEW
 107 # cd /srv/dak/queue/unchecked
 108 # dak process-upload *.changes
 109
 110 -----------------------------------------------------------------------
 111 hello_2.6-1_amd64.changes
 112 NEW for unstable
 113
 114
 115 (new) hello_2.6-1.debian.tar.gz optional devel
 116 (new) hello_2.6-1.dsc optional devel
 117 (new) hello_2.6-1_amd64.deb optional devel
 118 The classic greeting, and a good example
 119  The GNU hello program produces a familiar, friendly greeting.  It
 120  allows non-programmers to use a classic computer science tool which
 121  would otherwise be unavailable to them.
 122  .
 123  Seriously, though: this is an example of how to do a Debian package.
 124  It is the Debian version of the GNU Project's `hello world' program
 125  (which is itself an example for the GNU Project).
 126 (new) hello_2.6.orig.tar.gz optional devel
 127 Changes: hello (2.6-1) unstable; urgency=low
 128  .
 129   * New upstream release.
 130   * Drop unused INSTALL_PROGRAM stuff.
 131   * Switch to 3.0 (quilt) source format.
 132   * Standards-Version: 3.9.1 (no special changes for this).
 133
 134
 135 Override entries for your package:
 136
 137 Announcing to debian-devel-changes@lists.debian.org
 138
 139 [N]ew, Skip, Quit ?N
 140 Moving to NEW queue.
 141 Sending new ack.
 142 -----------------------------------------------------------------------
 143
 144 We can now look at the NEW queue-report
 145 # dak queue-report
 146 -----------------------------------------------------------------------
 147 NEW
 148 ---
 149
 150 hello | 2.6-1 | source amd64 | 5 seconds old
 151
 152 1 new source package / 1 new package in total.
 153 -----------------------------------------------------------------------
 154
 155 And we can then process the NEW queue:
 156 # cd /srv/dak/queue/new
 157 # dak process-new *.changes
 158
 159 -----------------------------------------------------------------------
 160 hello_2.6-1_amd64.changes
 161 NEW
 162
 163 hello                optional             devel
 164 Add overrides, Edit overrides, Check, Manual reject, Note edit, Prod, [S]kip, Quit ?A
 165 ACCEPT
 166 -----------------------------------------------------------------------
 167
 168 At this stage, the package has been ACCEPTed from NEW into NEWSTAGE.
 169 We now need to finally ACCEPT it into the pool:
 170
 171 # cd /srv/dak/queue/newstage
 172 # dak process-upload *.changes
 173
 174 -----------------------------------------------------------------------
 175 hello_2.6-1_amd64.changes
 176 ACCEPT
 177
 178
 179 hello_2.6-1.debian.tar.gz
 180   to main/h/hello/hello_2.6-1.debian.tar.gz
 181 hello_2.6-1.dsc
 182   to main/h/hello/hello_2.6-1.dsc
 183 hello_2.6-1_amd64.deb
 184   to main/h/hello/hello_2.6-1_amd64.deb
 185 hello_2.6.orig.tar.gz
 186   to main/h/hello/hello_2.6.orig.tar.gz
 187
 188
 189 Override entries for your package:
 190 hello_2.6-1.dsc - optional devel
 191 hello_2.6-1_amd64.deb - optional devel
 192
 193 Announcing to debian-devel-changes@lists.debian.org
 194 [A]ccept, Skip, Quit ?A
 195 Installing.
 196 Installed 1 package set, 646 KB.
 197 -----------------------------------------------------------------------
 198
 199 We can now see that dak knows about the package:
 200 # dak ls -S hello
 201
 202 -----------------------------------------------------------------------
 203      hello |      2.6-1 |      unstable | source, amd64
 204 -----------------------------------------------------------------------
 205
 206 # dak control-suite -l unstable
 207
 208 -----------------------------------------------------------------------
 209 hello 2.6-1 amd64
 210 hello 2.6-1 source
 211 -----------------------------------------------------------------------
 212
 213 Next, we can generate the packages and sources files:
 214 # dak generate-packages-sources2
 215 (zcat /srv/dak/ftp/dists/unstable/main/binary-amd64/Packages.gz for instance)
 216
 217 And finally, we can generate the signed Release files:
 218 # dak generate-release
 219
 220 -----------------------------------------------------------------------
 221 Processing unstable
 222 -----------------------------------------------------------------------
 223 (Look at /srv/dak/ftp/dists/unstable/Release, Release.gpg and InRelease)
 224
 225
 226 #######################################################################
 227 # Next steps
 228 #######################################################################
 229
 230 The debian archive automates most of these steps in jobs called
 231 cron.unchecked, cron.hourly and cron.dinstall.
 232
 233 TODO: Write example (simplified) versions of these cronjobs which will
 234 do for most installs.