Guruprasad has proposed merging ~lgp171188/turnip:revamp-development-environment-setup-docs into turnip:master.
Commit message: Revamp the development environment setup docs Requested reviews: Launchpad code reviewers (launchpad-reviewers) For more details, see: https://code.launchpad.net/~lgp171188/turnip/+git/turnip/+merge/448680 -- Your team Launchpad code reviewers is requested to review the proposed merge of ~lgp171188/turnip:revamp-development-environment-setup-docs into turnip:master.
diff --git a/docs/development.rst b/docs/development.rst index aeb1b72..150ad9a 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -1,35 +1,56 @@ Development =========== +Prerequisites +------------- + +* LXD is installed and set up. See + `<https://documentation.ubuntu.com/lxd/en/latest/getting_started/>`_ + for more details. + +* A working Launchpad development environment is available. See + `<https://launchpad.readthedocs.io/en/latest/how-to/running.html>`_ for more + details. + +* A local user on the Launchpad development instance with an SSH key added. + Use the ``utilities/make-lp-user`` script inside the Launchpad container + to create a new user account. This script looks for SSH public keys in + the home directory of the user and automatically adds them to the created + account. + + Setup ----- -Create a bionic container (optional): +These instructions should work with Ubuntu 18.04 (bionic) or 20.04 (focal). + +Create a LXD container. .. code:: bash lxc launch ubuntu:bionic turnip-bionic -p ${USER} -(You may want to use a profile to bind-mount your home directory as well.) +Replace ``bionic`` in the above command with ``focal`` to create a +``focal`` container. + +It is useful to use a LXD profile to bind-mount your home directory inside +this container. See the `Launchpad setup guide`_ for an example of how to +do this. -SSH into the new container and navigate to the turnip repo. +.. _Launchpad setup guide: https://launchpad.readthedocs.io/en/latest/how-to/running.html#create-a-lxd-container -Create a python virtual env: +Log in into the new container using SSH and navigate to the turnip repo. + +Create a Python virtual environment. .. code:: bash + sudo apt update + sudo apt install -y python3-venv python3 -m venv env source env/bin/activate -.. note:: - If you created a container, you may need to install python virtual env: - - .. code:: bash - - sudo apt-get update - sudo apt-get install -y python3-venv - -Run the following: +Run the following commands to install turnip's dependencies and bootstrap it. .. code:: bash @@ -40,7 +61,8 @@ Run the following: mkdir -p /var/tmp/git.launchpad.test .. note:: - If you are running a different ubuntu version on your container (e.g. focal), you might need to run: + If you are running a different Ubuntu version on your container + (e.g. focal), you might need to run: .. code:: bash @@ -50,49 +72,41 @@ Run the following: Running ------- -Pack smart-http/ssh services can be started with: +Start the pack smart-http/ssh services with: .. code:: bash make run-pack -The HTTP API can be started with: +Start the HTTP API with: .. code:: bash make run-api -Running LP locally as a Git client to Turnip --------------------------------------------- +Running Launchpad locally as a Git client to turnip +--------------------------------------------------- -Turnip container needs to be able to talk to xmlrpc-private.launchpad.test. +The turnip container needs to be able to communicate with +``xmlrpc-private.launchpad.test`` for this to work. -In the turnip container the hosts file needs to point to the LP container -(x.x.x.x is the IP address of LP): +In the turnip container, update the hosts file to point to the Launchpad +container, where ``x.x.x.x`` is its IP address. .. code:: bash user@turnip-bionic:~/turnip$ cat /etc/hosts - 127.0.0.1 localhost + ... x.x.x.x launchpad.test 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 - # The following lines are desirable for IPv6 capable hosts - ::1 ip6-localhost ip6-loopback - fe00::0 ip6-localnet - ff00::0 ip6-mcastprefix - ff02::1 ip6-allnodes - ff02::2 ip6-allrouters - ff02::3 ip6-allhosts - -A basic test that can be performed by dropping into the turnip container shell. -Below exception is expected as Repository ``1`` did not exist when the RPC -call was performed, it does show however that turnip is able to resolve -``xmlrpc-private.launchpad.test`` and there is connectivity between LP and -turnip: + ... + +Perform a basic test of the connectivity by running the following +commands and statements. .. code:: bash - user@launchpad:~$ lxc exec turnip-bionic python3 + user@launchpad:~$ lxc exec turnip-bionic python3 .. code:: python @@ -106,25 +120,35 @@ turnip: >>> exit() root@turnip-bionic:~# -In your LP container the hosts file needs to point to the turnip container -(x.x.x.x is the IP address of turnip): +The above exception is expected as ``Repository '1'`` did not exist when +the RPC call was performed. But it shows that turnip is able to resolve +``xmlrpc-private.launchpad.test`` and that there is connectivity between +Launchpad and turnip. + +In the Launchpad container, update the hosts file to point to the turnip +container, where ``x.x.x.x`` is its IP address. + +.. code:: bash + user@launchpad:~$ cat /etc/hosts + ... x.x.x.x git.launchpad.test + ... -Then, also in your LP container edit ~/.gitconfig and add these lines, -where USER is your Launchpad username: +Also edit ``~/.gitconfig`` in the Launchpad container and add these lines, +where ``USER`` is your Launchpad username on the local instance. .. code:: bash - [url "git+ssh://[email protected]/"] + [url "git+ssh://[email protected]:9422/"] insteadof = lptest: -Create a new repository locally (user@launchpad:~/repo in LP container in below -example) and push it to LP&Turnip: +Create a new repository, ``~/repo`` in the Launchpad container and push it +to turnip. .. code:: bash - user@launchpad:~/repo$ git remote add origin git+ssh://[email protected]:9422/~user/+git/repo + user@launchpad:~/repo$ git remote add origin lptest:~user/+git/repo user@launchpad:~/repo$ git push --set-upstream origin master Counting objects: 3, done. Writing objects: 100% (3/3), 231 bytes | 231.00 KiB/s, done. @@ -132,10 +156,10 @@ example) and push it to LP&Turnip: To git+ssh://git.launchpad.test:9422/~user/+git/repo * [new branch] master -> master Branch 'master' set up to track remote branch 'master' from 'origin'. - user@launchpad:~/repo$ + user@launchpad:~/repo$ -The LP log for above push: +The Launchpad log for above push should look like: .. code:: @@ -157,32 +181,28 @@ The LP log for above push: 10.209.173.202 - "" "xmlrpc-private.launchpad.test" [16/Dec/2019:13:41:18 +0300] "POST /git HTTP/1.0" 200 588 7 0.0113499164581 0.00207781791687 0.00744009017944 "Anonymous" "GitApplication:" "" "Twisted/XMLRPClib" -Your local LP user must exist in LP - created with -``utilities/make-lp-user USER`` - and have an ssh key in local LP. -When adding the SSH key to LP if emails can't go out the SSH key addition will -fail. -One possible workaround is to use Fakeemail: -https://github.com/tomwardill/fakeemail +When creating and pushing new branches to turnip with this local setup, +the branches have to be scanned (data about the branch copied into the +Launchpad database) for Launchpad to know about them. -It is recommended to install it in a virtual environment, -e.g. via `pipx <https://pypa.github.io/pipx/>`_: +Run the following command in the Launchpad container from the top-level +directory of the Launchpad repository to make Launchpad scan the git +branches. .. code:: bash - pipx install fakeemail - ~/.local/bin/fakeemail 25 8082 0.0.0.0 - Message stored for: root@localhost + cronscripts/process-job-source.py IGitRefScanJobSource + +Now the branch should be up-to-date and you can view it in the branch page +in the local Launchpad instance. -When creating and pushing new branches to LP with this local setup, -the branches need to be scanned (data about the branch copied into the -Launchpad database). -On production, this happens via the magic of cron. -Locally you can make it happen by running in your launchpad directory: +Now you can create a merge proposal from a branch. After creating it, generate +the preview diff for the merge proposal by running the following command +inside the Launchpad container from the top-level directory of the Launchpad +repository. .. code:: bash - cronscripts/process-job-source.py IGitRefScanJobSource + cronscripts/process-job-source.py IBranchMergeProposalJobSource -Now you have a fully working and up-to-date branch. -You should be able to look at the branch page in Launchpad, -view the source in codebrowse, and so on. +These commands are automatically run in the production environment by cron jobs.
_______________________________________________ Mailing list: https://launchpad.net/~launchpad-reviewers Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-reviewers More help : https://help.launchpad.net/ListHelp
