= Server setup =

== Run time dependencies ==

 * bzr (to grab the branch)
 * pxz | xz-utils
 * python3, python3-gpgme | python, python-gpgme
 * e2fsprogs
 * android-tools-fsutils
 * abootimg
 * fakeroot
 * apache2

== Test dependencies ==

 * python-tox
 * python-nose2, python3-nose2
 * python-mock, python3-mock
 * python-coverage, python3-coverage
 * libjs-jquery-hotkeys, libjs-jquery-isonscreen, libjs-jquery-tablesorter
 * pep8
 * pyflakes (includes executables for both Python 2 and 3)
 * both pxz and xz-utils (for 100% coverage)
 * cpio


== Web server setup ==
{{{
sudo adduser $USER www-data
sudo chgrp www-data /var/www/
sudo chmod g+rwX /var/www/
sudo rm -f /var/www/html/index.html
}}}

== Setting up the server itself ==
This assumes all the above was installed and done, that the code is running as an "ubuntu" user in its default home directory, on a server accessible at system-image.test.com with a valid SSL certificate on port 443.

{{{
bzr branch lp:~ubuntu-system-image/ubuntu-system-image/server system-image
cd system-image
tools/generate-keys
tox -e fast-py34,fast-py27
}}}

At this stage, you have the branch on your system, have generated some GPG keys (albeit test ones), and tested that the code works (at least the fast-path tests).  Now it's time to generated the matching keyrings, but first you have to configure the system by creating "etc/config" containing:

{{{
[global]
base_path = /home/ubuntu/system-image/
channels = test
gpg_key_path = secret/gpg/keys/
gpg_keyring_path = secret/gpg/keyrings/
publish_path = /var/www/
state_path = state/
public_fqdn = system-image.test.com
public_http_port = 80
public_https_port = 443

[channel_test]
type = auto
versionbase = 1
fullcount = 15
files = ubuntu, device, custom-savilerow, keyring, version
file_ubuntu = remote-system-image;https://system-image.ubuntu.com;trusty-proposed;ubuntu
file_device = remote-system-image;https://system-image.ubuntu.com;trusty-proposed;device;keyring=archive-master
file_custom-savilerow = http;https://jenkins.qa.ubuntu.com/job/savilerow-watch/lastSuccessfulBuild/artifact/custom.tar.xz;name=custom-savilerow,monitor=https://jenkins.qa.ubuntu.com/job/savilerow-watch/lastSuccessfulBuild/artifact/build_number
file_keyring = keyring;archive-master
file_version = version
}}}

You may want to look at config.example for all possible key values.

Relative paths, such as the {{{gpg_key_path}}} and {{{gpg_keyring_path}}} are relative to {{{base_path}}}.

The above defines a server accessible at system-image.test.com, which listens for http on port 80 and for https on port 443, has one channel that's managed by the importer, that channel is configured to contain 5 tarballs:
 * ubuntu => Ubuntu root filesystem, imported as-is from system-image.ubuntu.com
 * device => Device tarball, imported from system-image.ubuntu.com and then repacked to swap the GPG keys
 * custom-savilerow => Imported from an http server (customization tarball)
 * keyring => Contains the GPG keys that override those from the ubuntu tarball
 * version => Contains the channel configuration and current build data

Now that the configuration is done, you can generate the keyrings.

{{{
cp -R tools/keys/* <base_path>/secret/gpg/keys/
bin/generate-keyrings
}}}

Now we need to actually create the channels, add a device and publish the keyrings, for that, run "bin/si-shell" and do:

{{{
pub.create_channel("test")
pub.create_device("test", "mako")
for keyring in ("archive-master", "image-master", "image-signing", "blacklist"):
    pub.publish_keyring(keyring)
}}}

'''Note:''' you might want to omit {{{blacklist}}} if you don't have one, since {{{publish_keyring()}}} will give you an error if there is no blacklist keyring (there usually isn't by default).

At this point, your server is ready, all you need to do now is generate images by running: {{{bin/import-images -v}}}

== copy-image ==

On the actual system-image server {{{bin/copy-image}}} is used to copy images between channels, set up aliases, etc.  Since this is a local file system copy, and {{{copy-image}}} requires a source channel, you need to make a local mirror of a device/channel directory, and the related metadata files, on your local file system.  One way you could do that is a recursive {{{wget}}} of http://system-image.ubuntu.com but be prepared to devote tens of gigs of local disk space and saturate your network for a few days.

A better way is to use the [[https://code.launchpad.net/~barry/ubuntu-system-image/grabber/+merge/259055|grabber]] script which will mirror just enough locally to run {{{copy-image}}}.  You need to have the {{{system-image-common}}} package (v3.0 or newer) installed, since {{{grabber}}} uses bits and pieces from the system-image client to do the work of resolving which files are needed for which device/channel pair.  Thus, you'll also need Python 3.

Let's say you want to run the following {{{copy-image}}} command:

{{{
$ bin/copy-image -vvvv -p 6 ubuntu-touch/rc/bq-aquaris.en ubuntu-touch/ubuntu-rtm/14.09 krillin 23
}}}

You need to have the source channel (i.e. the first path argument) laid out locally.  Let's say further that you're going to build all this in {{{/tmp/si}}}.  Run the grabber like so:

{{{
$ cd /path/to/server/branch
$ bin/grabber -c ubuntu-touch/rc/bq-aquaris.en -d krillin /tmp/si
}}}

If you don't have {{{system-image-common}}} v3.0 or newer installed, do {{{bzr branch lp:ubuntu-system-image}}} and put the resulting directory on your {{{$PYTHONPATH}}}.

The {{{grabber}}} script will run for a while (but trust me, it's much faster than a full mirror!) and when it's done, you can now run {{{copy-image}}} after setting up your {{{etc/config}}} properly.

Oh yeah, what are those funky version-*.json files for?  They're consumed by {{{copy-image}}} to produce the version-details in the channels.ini file.