Deployment
==========

This page covers production deployment of the application as well as
common database operations needed during deploys and migrations.

Deploying with Docker Compose
-----------------------------

The recommended deployment uses the prebuilt Docker image
``n1cz/richy:nightly``. The repository ships a ready-to-use
``compose.yaml.skel`` file in the project root.

1. Copy the templates into place and edit them:

   .. code-block:: bash

       $ cp .env.skel .env
       $ cp compose.yaml.skel compose.yaml
       $ cp nginx.conf.skel nginx.conf

2. Pull the latest image:

   .. code-block:: bash

       $ docker pull n1cz/richy:nightly

3. Bring the stack up:

   .. code-block:: bash

       $ docker compose up -d

4. Load the predefined admin user (only on a fresh database):

   .. code-block:: bash

       $ docker exec -it richy ./manage.py loaddata users

   Default credentials are ``admin@test.com`` / ``test`` -- change
   them right after the first login.

The ``compose.yaml.skel`` runs five core services: ``richy`` (gunicorn),
``beat`` (celery beat), ``worker``, ``worker_slow``, ``worker_fast``,
plus ``redis``, ``db`` (Postgres) and ``nginx``. See
:doc:`/architecture/tasks` for details on the worker queues.

Environment variables
---------------------

Required environment variables come from ``.env``. The minimum set is
listed in :doc:`/getting_started/local_setup`; the full reference is in
:doc:`/architecture/settings`.

Manual production image build
-----------------------------

Same image as CI builds:

.. code-block:: bash

    $ docker build -t n1cz/richy:nightly .

Database dump
-------------
To dump the database use following command (which also bzip the dump):

.. code-block:: bash

    # (no news_news table)
    $ docker exec -it richy-db pg_dump -T news_news -U postgres richy | bzip2 -9f > /tmp/dump.sql.bz2
    # (full dump)
    $ docker exec -it richy-db pg_dump -U postgres richy | bzip2 -9f > /tmp/dump.sql.bz2

Transfer from a VPS to local and unzip the dump to current directory:

.. code-block:: bash

    $ rsync vps:/tmp/dump.sql.bz2 /tmp ; bzip2 -df /tmp/dump.sql.bz2 -c > dump.sql

Loading a dump assumes the compose file mounts the dump file as
``- ./dump.sql:/docker-entrypoint-initdb.d/dump.sql`` under the database
volumes. Recreate the db container to trigger the bootstrap import:

.. code-block:: bash

   $ docker rm richy-db; dcd up db

To load the dump manually:

.. code-block:: bash

    $ docker cp dump.sql richy-db:/tmp/dump.sql
    $ docker exec richy-db psql -U postgres -f /tmp/dump.sql

To run dump, transfer and load in one command:

.. code-block:: bash

   $ ssh vps "docker exec richy-db pg_dump -U postgres richy | bzip2 -9f > /tmp/dump.sql.bz2" \
       ; rsync vps:/tmp/dump.sql.bz2 /tmp \
       ; bzip2 -df /tmp/dump.sql.bz2 -c > dump.sql \
       ; docker rm richy-db; dcd up db

Updating an existing deployment
-------------------------------

.. code-block:: bash

    $ docker pull n1cz/richy:nightly
    $ docker compose up -d

The application doesn't ship breaking changes. When it does, release
notes describe the migration path -- watch the GitLab releases page.