Run-in-docker manual

Option 1 - Using an ansible playbook

These steps are meant for RefStack developers to help them with setting up a local refstack instance.

In production RefStack server is managed by a set of playbooks and ansible roles defined in system-config repository. This option takes advantage of those.

The RefStack server is running on Ubuntu 20.04 LTS in the production.

You can find an ansible playbook in playbooks directory which semi-automates the process of running refstack server in a container.

Execute the playbook by:

$ ansible-playbook playbooks/run-refstack-in-container.yaml

In order to avoid setting certificates and https protocol (it’s simpler and more than enough for a testing instance), edit /etc/apache2/sites-enabled/000-default.conf like following:

  • remove VirtualHost section for the port 80 and change the port of VirtualHost from 443 to 80

  • Turn off the SSLEngine (SSLEngine on -> SSLEngine off)

  • Remove SSLCertificate lines

and then restart the apache service so that it loads the new configuration:

$ systemctl restart apache2

How to edit refstack files within the container

List the running container by:

$ docker container list

You can enter the container by:

$ sudo docker exec -it <container name> /bin/bash
If you wanna install new packages like f.e. vim, do the following::

$ apt update $ apt install vim

Edit what’s needed, backend is installed under /usr/local/lib/python3.7/site-packages/refstack/ and frontend source files can be found at /refstack-ui

After you made the changes, make pecan to reload the files served:

$ apt install procps  # to install pkill command
$ pkill pecan

Killing pecan will kick you out of the container, however, pecan serves the edited files now and you may re-enter the container.

Installing refstack with changes put for a review

In order to do this, you will need to rebuild the refstack image built by the playbook.

Go to the location where the playbook downloaded system-config, default in /tmp/refstack-docker and edit the refstack’s Dockerfile:

$ cd /tmp/refstack-docker
$ vim ./refstack-docker-files/Dockerfile

Replace:

$ RUN git clone https://opendev.org/osf/refstack /tmp/src

by:

$ RUN git clone https://opendev.org/osf/refstack.git /tmp/src \
  && cd /tmp/src && git fetch "https://review.opendev.org/osf/refstack" \
  refs/changes/37/<change id/<patchset number> && git checkout -b \
  change-<change id>-<patchset number> FETCH_HEAD

Then rebuild the image:

$ docker image build -f Dockerfile -t <name:tag> .

Edit the docker-compose.yaml stored (by default) in /etc/refstack-docker/docker-compose.yaml and change the the image (under refstack-api) to your image name and tag you set in the previous step.

After then spin a new container using the new image:

$ cd /etc/refstack-docker
$ docker-compose down  # if refstack container is already running
$ docker-compose up -d

To see the server’s logs use the following command:

$ docker container logs -f <container name>

Option 2 - Using a script

NOTE: This is currently outdated, follow the Option 1 for now.

The main purpose of the run-in-docker script is to provide a convenient way to create a local setup of RefStack inside a Docker container. It should be helpful for new developers and also for testing new features.

Requirements:

  • Docker >= 1.6 (How to update on Ubuntu)

How to use:

Just run the run-in-docker script, but is important to first set env[REFSTACK_HOST] with the public host/IP for your local API. If you want to test RefStack with OpenStackid you should point a valid local alias here. For example:

export REFSTACK_HOST=myrefstack.com

By default 127.0.0.1 is used.

After it completes, check that the site is running on https://127.0.0.1.

The script will build a RefStack docker image with all dependencies, and will run a container from this image. By default, RefStack will run inside this container. You also can run run-in-docker bash to get access into the container. If you stop the RefStack server by pressing ‘Ctrl-C’, the container is kept alive and will be re-used next time.

You can customize the RefStack API config by editing docker/templates/refstack.conf.tmpl. It is a bash template, so you can use ${SOME_ENV_VARIABLE} in it.

This script can make the reviewing process much easier because it creates separate containers for each review. Containers get names in the form refstack_{REVIEW-TOPIC}. Database schema changes are automatically handled, too, where the script creates a data container for each database revision (refstack_data_{DATA-BASE-REVISON}) and reuses it where possible. For example, if a new review uses an existing database revision, that database container will be used.

Available script options:

  • -r Force delete the RefStack container and run it again. This will update the RefStack config from template noted above.

  • -i Run a container with isolated MySQL data. By default MySQL data is stored in a refstack_data_{DATA-BASE-REVISON} container. It reuses this container if such one exists. If you want to drop the DB data, just execute sudo docker rm refstack_data_{DATA-BASE-REVISON}.

  • -b Force delete RefStack image and build it again. This rebuilds the Python and JS environment for RefStack.

  • -d Turn on debug information.

  • -h Print usage message.

Useful in-container commands/aliases:

  • api-up - sync project and run the RefStack API

  • api-init-db - initialize the RefStack database

  • api-db-version - get current migration version of the RefStack database

  • api-sync - sync project files in the container with the project files on the host

  • activate - activate the python virtual env

  • mysql - open the MySQL console