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