Setting up and running Launchpad (2024)

Note

Ask for help right away if you runinto problems.

This page explains how to set up and run Launchpad (for development) on yourown machine, using a LXD-managed container toisolate it from the rest of your system.

After you’ve done this, you may want to read aboutNavigating the tree.

Supported operating systems¶

For the host system, any reasonably modern Ubuntu release should work.Other Linux distributions that have LXD should work too, though we don’ttest on them.

Launchpad requires Ubuntu 20.04 LTS with Python 3.8. Ubuntu 22.04 is known notto work yet.

We’d like Launchpad to run on other operating systems, especially DebianGNU/Linux, so that more people can contribute toLaunchpad development. If you’re interested in working on Launchpadportability, please let us know. Notethat our focus is on getting Launchpad to build easily so more people canparticipate in Launchpad development. Running a stable production instancewould be much harder than running a single-developer test instance, and wedon’t recommend it. Unlike many open source projects, we’re not seeking tomaximize the number of installations; our goal is to improve the instancewe’re already running.

Why use LXD containers?¶

Launchpad development setup makes significant changes to your machine; it’snice to be unaffected by those when you’re not doing such development.Using containers means that the version of Ubuntu on your host systemdoesn’t need to match Launchpad’s requirements. Multiple containers can beused to work around Launchpad’s limitations regarding concurrent test runson a single machine.

LXD also has some nice snapshotting and ZFS capabilities, and is what otherLaunchpad developers use, so other people will be able to help you debugyour setup if needed.

The installation script is written with the assumption that it will berunning inside such a container. If you run it on your host system, it maywell break it.

Create a LXD container¶

This assumes you already have LXD set up. If not, follow the instructions forgetting it installed and configured on your network.

If you haven’t done so already, run this script to set up LXD to let youuse your home directory inside the container. Some developers prefer toonly mount a subdirectory of their home directory in the container: to dothat, replace $HOME with $HOME/src or similar. Although it maybe tempting, make sure not to call your local user “launchpad”, as thatwill break; see Database permissions.

#! /bin/shid=400000 # some large uid outside of typical range, and outside of already mapped ranges in /etc/sub{u,g}iduid=$(id -u)gid=$(id -g)user=$(id -un)group=$(id -gn)# give lxc permission to map your user/group id throughsudo usermod --add-subuids ${uid}-${uid} --add-subgids ${gid}-${gid} root# create a profile to control thislxc profile create $user >/dev/null 2>&1# configure profilecat << EOF | lxc profile edit $username: $userdescription: allow home dir mounting for $userconfig: raw.idmap: | uid $uid $id gid $gid $id user.user-data: | #cloud-config runcmd: - "groupadd $group --gid $id" - "useradd $user --uid $id --gid $group --groups adm,sudo --shell /bin/bash" - "echo '$user ALL=(ALL) NOPASSWD:ALL' >/etc/sudoers.d/90-cloud-init-users" - "chmod 0440 /etc/sudoers.d/90-cloud-init-users"devices: home: type: disk source: $HOME path: $HOMEEOF

Create a container. This command creates a Ubuntu 20.04 unprivilegedcontainer using the profile created in the previous step.

lxc launch ubuntu:20.04 lpdev -p default -p $USER

Note

If the command above fails with Error: No root device could be found, you may need to run

lxd init

This will ensure you have initialized your LXD storage.

Find the container IP, either from lxc list or lxc info lpdev.

Note

If your new container does not have an IPv4 address when you run lxc list,see Network Connectivity in Troubleshooting section.

In order to be able to ssh into the container, you need to add yourpublic key to your local .ssh/authorized_keys configuration. Alsomake sure that both .ssh (700) and authorized_keys (600) have thecorrect permissions.
See Also
PPA › Paketquellen freischalten › Wiki › ubuntuusers.de Projects/Registering - Launchpad Help Code/QuickStart - Launchpad Help Packaging/PPA/Uploading - Launchpad Help
Connect as follows. (The -A permits you to access Launchpad code hostingfrom within the container without needing to reenter passphrases.)

ssh -A $USER@IP_ADDRESS_FROM_LXC_LS

Note

LXD provides a way to access the LXD containers using DNS names, for example, lpdev.lxd,where .lxd is the default base domain name for the LXD bridge and lpdev is the name ofthe LXD container. To set this up, follow the instructions inhttps://documentation.ubuntu.com/lxd/en/latest/howto/network_bridge_resolved/.Once the setup is done, you can use lpdev.lxd in the above command instead of theIP address of the lpdev container.

Getting Launchpad¶

Do all this inside the container you set up previously. Be aware thatchanges in your home directory inside the container will also be seenoutside the container and vice versa.

If your Launchpad username differs from your local one, then put this in~/.ssh/config in the container before doing anything else, replacingLPUSERNAME with your Launchpad username:

Host bazaar.launchpad.net User LPUSERNAMEHost git.launchpad.net User LPUSERNAME

Then:

$ mkdir ~/launchpad$ cd ~/launchpad$ curl https://git.launchpad.net/launchpad/plain/utilities/rocketfuel-setup >rocketfuel-setup

Read through the rocketfuel-setup script at this point and make sure you’reOK with what it’s going to do. (See Launchpad installation details if you want toknow more.)

$ chmod a+x rocketfuel-setup$ ./rocketfuel-setup

This will take a while – maybe a few hours to get everything, depending onyour Internet connection.

Note that you will be prompted for your sudo password, and for aLaunchpad login ID (that is, your username on launchpad.net). The sudoaccess is necessary to get Launchpad running on your box; the Launchpadlogin is not strictly necessary, and you can just hit Return there if youwant. See below for an explanation.

Note that this will make changes to your Apache configuration if you alreadyhave an Apache server in your container. It will also add entries to/etc/hosts, and it will setup a PostgreSQL server in your container.

If you are running rocketfuel-setup to bring up a new container but yourhome directory already has a usable Launchpad tree, you can pass--no-workspace to only perform the system-wide setup.

Note that if rocketfuel-setup bails out with instructions to fixsomething, you just need to run it again and it should pick up where it leftoff.

$ sudo apt full-upgrade

This is just to make doubly-sure everything from the Launchpad PPA getsinstalled.

$ lslaunchpad/ lp-sourcedeps/ rocketfuel-setup$ cd launchpad

You are now in a newly-cloned Git repository, with one branch (‘master’),into whose working tree the other source dependencies have been symlinked.The source dependencies actually live in ../lp-sourcedeps.

Installing the pre-commit hook¶

If you intend to make any changes to Launchpad, you should also set uppre-commit now:

Install pre-commit itself. If your host system is Ubuntu 20.10 ornewer, then sudo apt install pre-commit is enough; otherwise, you caninstall it in your user account (pipxworks well to keep it isolated; whatever you do, don’t run pipsystem-wide as root!). We require this to be installed separately ratherthan including it in Launchpad’s virtual environment because developerscommonly run git commit outside the container used for runningLaunchpad.
Install the pre-commit git hook by running pre-commit install inyour newly-cloned launchpad repository.

Building¶

Before you can run Launchpad for the first time, you need to set up PostgreSQL.

Note

DO NOT run the database setup script below if you use PostgreSQL foranything other than Launchpad! Running the script will destroy anyPostgreSQL databases on your system. Seehttps://dev.launchpad.net/DatabaseSetup for details.

$ ./utilities/launchpad-database-setup $USER

(Please have read the previous comment before you run the above command!)

Finally, build the database schema (this may take several minutes):

$ make schema

Running¶

Now you should be able to start up Launchpad:

$ make run

This only runs the basic web application. Codehosting and Soyuz require additionalsteps.

For subsequent builds, you can just do make run right away. You don’tneed to do make schema every time, and you should avoid it because it’sexpensive and because it will clean out any data you might have put intoyour test instance (through the web UI or by running other scripts).

CSS Watch¶

While running a local instance of Launchpad, if you are interested in updatingCSS or SCSS files, they will not re-render automatically.To enable that and make frontend changes more straight-forward, you can run:

$ make css_watch

This should be run in a separate terminal session alongside make run.

Accessing your web application¶

When running make run, your application is running in your container, but itis not yet accessible outside of it - this includes your host machine, i.e.,you won’t, for example, be able to access your application from your browser.

Unless the only thing you’re doing is running parts of the test suite, youprobably want to make your new Launchpad instance accessible from othermachines on the same local network, or in particular from the host system.

Amending the Apache configuration¶

Launchpad’s default development Apache config(/etc/apache2/sites-available/local-launchpad.conf) only listens on127.0.0.88. This can be overridden with the LISTEN_ADDRESS environmentvariable when running make install. You probably want to make it listenon everything:

$ sudo make LISTEN_ADDRESS='*' install

Amending the hosts file¶

Launchpad makes extensive use of virtual hosts, so you’ll need to addentries to /etc/hosts on any machine from which you want to access theLaunchpad instance.

Within the container running the instance, you can see the relevant hostnamesin /etc/hosts - these need to be added to the machine you want to accessthe application from, mapped to the server machine or container’s external IP address.

For example, to access the application in your host system (and your browser),you should copy the *.launchpad.test hostnames you see in the hosts filewithin the container running the application, and append them to your host system’shosts file, mapped to the IPv4 address of the container running the app.

This should look similar to this:

# Launchpad virtual domains. This should be on one line.<your container IPv4 address> launchpad.test answers.launchpad.test archive.launchpad.test api.launchpad.test bazaar.launchpad.test bazaar-internal.launchpad.test blueprints.launchpad.test bugs.launchpad.test code.launchpad.test feeds.launchpad.test keyserver.launchpad.test lists.launchpad.test ppa.launchpad.test private-ppa.launchpad.test testopenid.test translations.launchpad.test xmlrpc-private.launchpad.test xmlrpc.launchpad.test

Note

To access the application in a Windows machine, it may be helpful to know thatthe Windows equivalent of /etc/hosts is located atC:\WINDOWS\system32\drivers\etc\hosts. Note that Windows’ version has aline length limit, so you might have to split it across multiple lines oronly include the hostnames that you need.

You should now be able to access https://launchpad.test/ in a webbrowser on a suitably configured remote computer. Accept the localself-signed certificate. You can log in as admin@canonical.com withouta password. (This is only for development convenience, and assumes that youtrust machines that can route to your LXD containers; of course a productiondeployment would need real authentication.). If you want to create more useraccounts, see Manage users and teams in development environments.

Accessing launchpad.test from a single host over SSH¶

As an alternative to the above, SSH provides a SOCKS proxy. By running thatproxy on the target machine, you can view its Launchpad web site as if youwere on that machine, without having to open non-SSH ports to a widernetwork. To do so:

$ ssh -D8110 target-machine

Then set your browser’s SOCKS proxy settings to use target-machine:8110.

Stopping¶

You can stop Launchpad by hitting Control-C in the terminal where youstarted it:

^C[...shutting down Launchpad...]$

Or you can be at a prompt in the same directory and run this:

$ make stop

Troubleshooting¶

Network connectivity¶

“The LXC container is not getting an IPv4 address assigned and the networkconnectivity inside the container doesn’t work.”

On Ubuntu 21.10, ufw uses nftables by default, so if you are usingUbuntu 21.10 on the host and ufw is enabled with the default policy ofblocking incoming and routed traffic, the rules added by LXD will not takeeffect, and hence LXD’s traffic will be dropped.

The fix is to add ufw allow rules to allow incoming and routed trafficon the bridge interface, like this (replacing lxdbr0 with the name ofthe bridge interface on your computer):

sudo ufw allow in on lxdbr0sudo ufw route allow in on lxdbr0

Email¶

“I have Launchpad running but emails are not sent.”

Development Launchpads don’t send email to the outside world, for obviousreasons. They connect to the local SMTP server and send to root. To createnew users, create a new account and check the local mailbox, or seeManage users and teams in development environments.

Database permissions¶

“My database permissions keep getting deleted!”

If your local account is called “launchpad” it conflicts with a role called“launchpad” which is defined in database/schema/security.cfg. You needto rename your local account and re-assign it superuser permissions as theutilities/launchpad-database-setup script does.