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 /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/ && git checkout -b \ change-- FETCH_HEAD Then rebuild the image:: $ docker image build -f Dockerfile -t . 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 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