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 adduser dak
  20 # sudo addgroup ftpmaster
  21 # sudo addgroup dak ftpmaster
  22 # sudo -u postgres createuser -s dak
  23
  24 Set up the dak directory:
  25 # sudo mkdir /etc/dak
  26 # sudo mkdir /srv/dak
  27 # sudo chown dak:ftpmaster /srv/dak
  28 # sudo chmod 2775 /srv/dak
  29
  30 Create a symlink to /srv/dak/dak.conf in /etc/dak
  31 (we'll create the config file in a bit)
  32 # sudo ln -s /srv/dak/dak.conf /etc/dak/dak.conf
  33
  34 Become the dak user:
  35 # sudo -u dak -s -H
  36
  37 Create the additional roles:
  38 # createuser -S -R -D ftpmaster
  39 # createuser -S -R -D ftpteam
  40 # createuser -S -R -D ftptrainee
  41
  42 Create an empty database with SQL_ASCII encoding:
  43 # createdb -T template0 -E SQL_ASCII -O dak projectb
  44
  45 Import the schema:
  46 # psql -f current_schema.sql -d projectb
  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 # 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
  73 Remember the signing key id for when creating the suite below.
  74 Here we'll pretend it is DDDDDDDD for convenience
  75
  76 Import some developer keys.
  77 Either import from keyservers (here AAAAAAAA):
  78 # gpg --no-default-keyring --keyring /srv/dak/keyrings/upload-keyring.gpg --recv-key AAAAAAAA
  79 or import from files:
  80 # gpg --no-default-keyring --keyring /srv/dak/keyrings/upload-keyring.gpg --import /path/to/keyfile
  81
  82 Import the developer keys into the database
  83 The -U '%s' tells dak to add UIDs automatically
  84 # dak import-keyring -U '%s' /srv/dak/keyrings/upload-keyring.gpg
  85
  86 Add some architectures you care about:
  87 # dak admin architecture add i386 "Intel x86 port"
  88 # dak admin architecture add amd64 "AMD64 port"
  89
  90 Add a suite (origin=, label= and codename= are optional)
  91 signingkey= will ensure that Release files are signed
  92 # dak admin suite add-all-arches unstable x.y.z origin=MyDistro label=Master codename=sid signingkey=DDDDDDDD
  93
  94 Re-run dak init-dirs to add new suite directories to /srv/dak
  95 # dak init-dirs
  96
  97 #######################################################################
  98 # Example package flow
  99 #######################################################################
 100
 101 For this example, we've grabbed and built the hello source package
 102 for AMD64 and copied it into /srv/dak/queue/unchecked.
 103
 104 We start by performing initial package checks which will
 105 result in the package being moved to NEW
 106 # cd /srv/dak/queue/unchecked
 107 # dak process-upload *.changes
 108
 109 -----------------------------------------------------------------------
 110 hello_2.6-1_amd64.changes
 111 NEW for unstable
 112
 113
 114 (new) hello_2.6-1.debian.tar.gz optional devel
 115 (new) hello_2.6-1.dsc optional devel
 116 (new) hello_2.6-1_amd64.deb optional devel
 117 The classic greeting, and a good example
 118  The GNU hello program produces a familiar, friendly greeting.  It
 119  allows non-programmers to use a classic computer science tool which
 120  would otherwise be unavailable to them.
 121  .
 122  Seriously, though: this is an example of how to do a Debian package.
 123  It is the Debian version of the GNU Project's `hello world' program
 124  (which is itself an example for the GNU Project).
 125 (new) hello_2.6.orig.tar.gz optional devel
 126 Changes: hello (2.6-1) unstable; urgency=low
 127  .
 128   * New upstream release.
 129   * Drop unused INSTALL_PROGRAM stuff.
 130   * Switch to 3.0 (quilt) source format.
 131   * Standards-Version: 3.9.1 (no special changes for this).
 132
 133
 134 Override entries for your package:
 135
 136 Announcing to debian-devel-changes@lists.debian.org
 137
 138 [N]ew, Skip, Quit ?N
 139 Moving to NEW queue.
 140 Sending new ack.
 141 -----------------------------------------------------------------------
 142
 143 We can now look at the NEW queue-report
 144 # dak queue-report
 145 -----------------------------------------------------------------------
 146 NEW
 147 ---
 148
 149 hello | 2.6-1 | source amd64 | 5 seconds old
 150
 151 1 new source package / 1 new package in total.
 152 -----------------------------------------------------------------------
 153
 154 And we can then process the NEW queue:
 155 # cd /srv/dak/queue/new
 156 # dak process-new *.changes
 157
 158 -----------------------------------------------------------------------
 159 hello_2.6-1_amd64.changes
 160 NEW
 161
 162 hello                optional             devel
 163 Add overrides, Edit overrides, Check, Manual reject, Note edit, Prod, [S]kip, Quit ?A
 164 ACCEPT
 165 -----------------------------------------------------------------------
 166
 167 At this stage, the package has been ACCEPTed from NEW into NEWSTAGE.
 168 We now need to finally ACCEPT it into the pool:
 169
 170 # cd /srv/dak/queue/newstage
 171 # dak process-upload *.changes
 172
 173 -----------------------------------------------------------------------
 174 hello_2.6-1_amd64.changes
 175 ACCEPT
 176
 177
 178 hello_2.6-1.debian.tar.gz
 179   to main/h/hello/hello_2.6-1.debian.tar.gz
 180 hello_2.6-1.dsc
 181   to main/h/hello/hello_2.6-1.dsc
 182 hello_2.6-1_amd64.deb
 183   to main/h/hello/hello_2.6-1_amd64.deb
 184 hello_2.6.orig.tar.gz
 185   to main/h/hello/hello_2.6.orig.tar.gz
 186
 187
 188 Override entries for your package:
 189 hello_2.6-1.dsc - optional devel
 190 hello_2.6-1_amd64.deb - optional devel
 191
 192 Announcing to debian-devel-changes@lists.debian.org
 193 [A]ccept, Skip, Quit ?A
 194 Installing.
 195 Installed 1 package set, 646 KB.
 196 -----------------------------------------------------------------------
 197
 198 We can now see that dak knows about the package:
 199 # dak ls -S hello
 200
 201 -----------------------------------------------------------------------
 202      hello |      2.6-1 |      unstable | source, amd64
 203 -----------------------------------------------------------------------
 204
 205 # dak control-suite -l unstable
 206
 207 -----------------------------------------------------------------------
 208 hello 2.6-1 amd64
 209 hello 2.6-1 source
 210 -----------------------------------------------------------------------
 211
 212 Next, we can generate the packages and sources files:
 213 # dak generate-packages-sources2
 214 (zcat /srv/dak/ftp/dists/unstable/main/binary-amd64/Packages.gz for instance)
 215
 216 And finally, we can generate the signed Release files:
 217 # dak generate-release
 218
 219 -----------------------------------------------------------------------
 220 Processing unstable
 221 -----------------------------------------------------------------------
 222 (Look at /srv/dak/ftp/dists/unstable/Release, Release.gpg and InRelease)
 223
 224
 225 #######################################################################
 226 # Next steps
 227 #######################################################################
 228
 229 The debian archive automates most of these steps in jobs called
 230 cron.unchecked, cron.hourly and cron.dinstall.
 231
 232 TODO: Write example (simplified) versions of these cronjobs which will
 233 do for most installs.