Update Docker Testing

Docker-Testing.md

@@ -1 +1,120 @@
-TBA
+## Preface
+
+First, to make sure you're ready to go: ensure all
+[Dependencies](#dependencies) are on your system.
+
+When testing with Docker, the following sections should be read:
+
+- [Dummy Data](#dummy-data)
+- [Accounts](#accounts)
+
+If you plan to run benchmarks, please read the [Benchmarking](#benchmarking)
+section.
+
+To begin with aurweb's Docker infrastructure, see
+[Getting Started](#getting-started).
+
+## Dependencies
+
+The following table lists out requirements needed to run our `docker-compose`
+services:
+
+| Package          | Distribution | Method                                  |
+|------------------|--------------|-----------------------------------------|
+| docker-compose   | Arch Linux   | `pacman -S docker-compose`              |
+| docker-compose   | Other        | https://docs.docker.com/engine/install/ |
+
+## Getting Started
+
+To run all services in the background:
+
+    $ FASTAPI_BACKEND=gunicorn FASTAPI_WORKERS=5 docker-compose up -d nginx
+
+The `FASTAPI_BACKEND` and `FASTAPI_WORKERS` environment variables control
+the backend and its number of workers we use to host the `fastapi` service.
+For testing, we should align `fastapi` as close as possible with `php`.
+
+Our `php-fpm` service uses `5` workers, so we should reflect that same
+worker count in our `fastapi` service. Additionally, we want to use
+the `gunicorn` backend, as it's what will be used in production.
+
+These variables' defaults can also be configured through
+[.env](https://gitlab.archlinux.org/archlinux/aurweb/-/tree/pu/.env).
+
+To stop services, including orphans:
+
+    $ docker-compose down --remove-orphans
+
+To view service logs, where `service` is one of the services described in the
+[Docker wiki page](https://gitlab.archlinux.org/archlinux/aurweb/-/wikis/Docker):
+
+    $ docker-compose logs [--follow] service
+
+## Dummy Data
+
+To test most features, the Docker instance needs some dummy data in
+it's database.
+
+To create dummy data, use the `schema/gendummydata.py` script, which
+can be configured using the following environment variables:
+
+- `MAX_USERS`
+    - default: 38000
+- `MAX_PKGS`
+    - default: 32000
+- `OPEN_PROPOSALS`
+    - default: 15
+- `CLOSE_PROPOSALS`
+    - default: 50
+- `FORTUNE_FILE`
+    - default: `/usr/share/fortune/cookie`
+
+**NOTE:** The `gendummydata.py` script requires the `bcrypt` Python
+dependency, which can be installed by `pip` or through the `python-bcrypt`
+package on Arch Linux.
+
+First, generate dummy data:
+
+    $ python schema/gendummydata.py dummy.sql
+
+Then, import that dummy data into Docker's mariadb service:
+
+    $ mysql -h127.0.0.1 -P13306 -uaur -paur aurweb <dummy.sql
+
+## Accounts
+
+Since you're using Docker, you have full control over the database.
+This opens up the ability for you to generate or register user accounts
+on your own.
+
+#### Dummy Users
+
+Users generated by `gendummydata.py` use the same value for both
+username and password.
+
+#### Registration
+
+First, register your own account with a valid email on
+https://localhost:8444/register.
+
+After registration, you will need to obtain the reset key from the
+mariadb database, since notifications are no-op:
+
+    $ mysql -h127.0.0.1 -P13306 -uaur -paur aurweb \
+        -e "SELECT ResetKey FROM Users WHERE Username = 'your_username'"
+
+Browse to https://localhost:8444/passreset?resetkey={reset_key},
+replacing `{reset_key}` with the real reset key. Here, you can set your
+password as long as you provide the correct username which matches
+`{reset_key}`.
+
+## Benchmarking
+
+For benchmark comparisons to be fair, the `fastapi` service must be
+configured to use a production backend (`gunicorn`) and `5` workers.
+The `php-fpm` service also uses `5` workers.
+
+To start up a Docker instance with a specific FastAPI backend and worker
+count, users can provide a few environment variables to `docker-compose`:
+
+    $ FASTAPI_BACKEND=gunicorn FASTAPI_WORKERS=5 docker-compose up -d nginx