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 <https://opendev.org/opendev/system-config.git>`__
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 <http://www.ubuntuupdates.org/ppa/docker>`__)
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