setup/README

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