From c5227283b4ae6eaf941600a78f67b30dad375104 Mon Sep 17 00:00:00 2001 From: Filip Valder Date: Fri, 16 Dec 2016 13:44:11 +0100 Subject: [PATCH] - partially update docs and re-format it - add 'Module submission' section - language fixes, thx to @mprahl --- docs/CONTRIBUTING.rst | 88 ++++++++++++++++++++++++++++--------------- 1 file changed, 58 insertions(+), 30 deletions(-) diff --git a/docs/CONTRIBUTING.rst b/docs/CONTRIBUTING.rst index 2f2f2e17..c6fac0d8 100644 --- a/docs/CONTRIBUTING.rst +++ b/docs/CONTRIBUTING.rst @@ -1,7 +1,8 @@ Development =========== -We have two mechanisms for quickly setting up a development environment. `docker-compose` and `vagrant`. +We have two mechanisms for quickly setting up a development environment, +`docker-compose` and `vagrant`. In order to to setup a development environment, it is required that you have your Fedora kerberos credentials generated in a *special location*. Before @@ -11,18 +12,21 @@ starting your development environment, run the following:: If you have problems in later steps with kerberos reading those credentials inside the `scheduler` container, you should check that `/var/tmp/krbcc` exists -on your machine and that *it is not a directory*. Try removing it with `$ sudo +on your machine and that *it is not a directory*. Try removing it with `$ sudo rm -rf /var/tmp/krbcc` and running `kinit` again. Also, check for permissions and SELinux context of the credentials cache file. PDC and pdc-updater ------------------- -For communication with PDC, you will need to check accessibility of `PDC_URL` -(see your local `config.py`). +To be able to communicate with PDC, your development instance will need to +be able to access the URL defined in the configuration option `PDC_URL`, +located in your local `conf/config.py` -For communication with pdc-updater, you will need SSH connection to the machine, -which provides development instance. +To communicate with pdc-updater, you will need to configure SSH on your host +machine to forward remote ports from pdc-updater's devel instance, typically +`modularity.fedorainfracloud.org`. This enables communication between PDC +and your Module Build Service development instance. Your `ssh_config` should look like this:: @@ -31,8 +35,9 @@ Your `ssh_config` should look like this:: User fedora RemoteForward 300x 127.0.0.1:5001 # x is one of 0...9 -Provided that this is configuration of endpoints where pdc-updater sits, typically -`/etc/fedmsg.d/endpoints.py` (on the machine given above):: +The configuration above assumes that the development instance with +pdc-updater has the following endpoints configured (typically in +`/etc/fedmsg.d/endpoints.py`). endpoints={ "rida.local": [ @@ -43,10 +48,10 @@ Provided that this is configuration of endpoints where pdc-updater sits, typical Docker ------ -You can use docker containers for development. Here's a guide on how to setup +You can use docker containers for development. Here's a guide on how to setup `docker `_ and `docker-compose `_ -for Fedora users (it's just a `dnf install` away). Mac users should see `these +for Fedora users (it's just a `dnf install` away). Mac users should see `these docs `_. After your docker engine is set up and running and docker-compose is installed, @@ -55,9 +60,7 @@ you can start the entire development environment with a single command:: $ sudo docker-compose up That will start a number of services in containers, including the `frontend` -and the backend `scheduler`. You can submit a local test build with the -`submit-build.py` script, which should submit an HTTP POST to the frontend, -requesting a build. +and the backend `scheduler`. You may want to wipe your local development database from time to time. Try the following commands, and you should have a fresh environment:: @@ -65,21 +68,24 @@ following commands, and you should have a fresh environment:: $ rm module_build_service.db $ docker-compose down -v && docker-compose up -If things get really screwy and your containers won't start properly, the best thing -to do is to rebuild the environment from scratch:: +If things get really screwy and your containers won't start properly, the +best thing to do is to rebuild the environment from scratch:: $ docker-compose down -v $ docker-compose build --no-cache --pull -The first command will stop and remove all your containers and volumes and the second -command will pull the latest base image and perform a clean build without using the cache. +The first command will stop and remove all your containers and volumes and +the second command will pull the latest base image and perform a clean build +without using the cache. Vagrant ------- -If you are using VirtualBox, you will need to install the Vagrant plugin `vagrant-vbguest`. -This plugin automatically installs guest additions to Vagrant guests that do not have them installed. -The official Fedora Vagrant box unfortunately does not contain the guest additions, and they are needed for folder syncing:: +If you are using VirtualBox, you will need to install the Vagrant plugin +`vagrant-vbguest`. This plugin automatically installs guest additions to +Vagrant guests that do not have them installed. The official Fedora Vagrant +box unfortunately does not contain the guest additions, and they are needed +for folder syncing:: $ vagrant plugin install vagrant-vbguest @@ -87,7 +93,8 @@ To launch Vagrant, run (depending on your OS, you may need to run it with sudo): $ vagrant up -This will start module_build_service's frontend (API) and scheduler. To access the frontend, visit the following URL:: +This will start module_build_service's frontend (API) and scheduler. To +access the frontend, visit the following URL:: https://127.0.0.1:5000/module-build-service/1/module-builds/ @@ -99,35 +106,55 @@ To start the frontend manually, run the following inside the guest:: $ mbs-frontend -To start the scheduler manually, run the following at `/tmp/module_build_service` inside the guest:: +To start the scheduler manually, run the following at +`/tmp/module_build_service` inside the guest:: $ fedmsg-hub -Alternatively, you can restart the Vagrant guest, which inherently starts/restarts the frontend and the scheduler with:: +Alternatively, you can restart the Vagrant guest, which inherently +starts/restarts the frontend and the scheduler with:: $ vagrant reload Logging ------- -If you're running module_build_service from scm, then the DevConfiguration from -`conf/config.py` which contains `LOG_LEVEL=debug` should get applied. See more about -it in `module_build_service/config.py`, `app.config.from_object()`. +If you're running module_build_service from scm, then the DevConfiguration +from `conf/config.py` which contains `LOG_LEVEL=debug` should get applied. See +more about it in `module_build_service/config.py`, `app.config.from_object()`. Environment ----------- -The environment variable `MODULE_BUILD_SERVICE_DEVELOPER_ENV`, which if set to "1", indicates to the Module Build Service that the development configuration should be used. Docker and Vagrant are being run with this environment variable set. +The environment variable `MODULE_BUILD_SERVICE_DEVELOPER_ENV`, which if +set to "1", indicates to the Module Build Service that the development +configuration should be used. Docker and Vagrant are being run with this +environment variable set. Anytime, you can do:: $ export MODULE_BUILD_SERVICE_DEVELOPER_ENV=1 +Module Submission +----------------- + +You can submit a local test build with the `contrib/submit_build.py` script, +which should submit an HTTP POST to the frontend, requesting a build:: + + $ cd contrib/ && python submit_build.py + +This script uses `scmurl` from the input file `contrib/submit-build.json`. Note +that authentication will be required for submitting a module build. Follow +the on-screen instructions to authenticate. + +See also `SCMURLS` in `conf/config.py` for list of allowed SCM URLs. + fedmsg Signing for Development ------------------------------ -In order to enable fedmsg signing in development, you will need to follow a series of steps. -Note that this will conflict with signed messages from a different CA that are on the message bus, so this may cause unexpected results. +In order to enable fedmsg signing in development, you will need to follow +a series of steps. Note that this will conflict with signed messages from +a different CA that are on the message bus, so this may cause unexpected results. Generate the CA, the certificate to be used by fedmsg, and the CRL with:: @@ -144,4 +171,5 @@ Create a directory to house the fedmsg cache:: $ mkdir -p /etc/pki/fedmsg -Then uncomment the fedmsg signing configuration in fedmsg.d/module_build_service.py. +Then uncomment the fedmsg signing configuration in +`fedmsg.d/module_build_service.py`.