setup/README

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