diff --git a/README.md b/README.md index 9ba64338..8ebefe13 100644 --- a/README.md +++ b/README.md @@ -28,11 +28,23 @@ Directory Layout * `upgrading`: instructions for upgrading setups from one release to another * `web`: PHP-based web interface for the AUR +Documentation +------------- + +| What | Link | +|--------------|--------------------------------------------------| +| Installation | [INSTALL](./INSTALL) | +| Testing | [test/README.md](./test/README.md) | +| Git | [doc/git-interface.txt](./doc/git-interface.txt) | +| Maintenance | [doc/maintenance.txt](./doc/maintenance.txt) | +| RPC | [doc/rpc.txt](./doc/rpc.txt) | +| Docker | [doc/docker.md](./doc/docker.md) | + Links ----- -* The repository is hosted at https://gitlab.archlinux.org/archlinux/aurweb -- see - doc/CodingGuidelines for information on the patch submission process. +* The repository is hosted at https://gitlab.archlinux.org/archlinux/aurweb + -- see doc/CodingGuidelines for information on the patch submission process. * Bugs can (and should) be submitted to the aurweb bug tracker: https://bugs.archlinux.org/index.php?project=2 diff --git a/doc/docker.md b/doc/docker.md new file mode 100644 index 00000000..22505f7a --- /dev/null +++ b/doc/docker.md @@ -0,0 +1,164 @@ +Table of Contents +----------------- + + + + + + + + + +
Getting StartedProfilesServices
+ +**Note:** The `docker-compose` infrastructure is experimental and +in need of improvements. + +Getting Started +--------------- + +Install required dependencies: + + # pacman -Syu docker-compose + +See [Profiles](#profiles) for details about using the different profiles +setup for aurweb. The following examples use the [default](#default) profile. + +Begin by building `aurweb:latest` off the current revision: + + $ docker-compose build + +You can run tests: + + $ docker-compose run test + +Or, start the development server: + + $ docker-compose up -d nginx + +See [nginx](#nginx) for details on connecting to the local instance. + +Profiles +-------- + +| Name | Options | +|---------|----------------------| +| default | `docker-compose ...` | +| aur-dev | `docker-compose -f docker-compose.yml -f docker-compose.aur-dev.yml ...` | + +#### default + +Default development profile intended to be used on local systems. + +#### aur-dev + +Production profile used for deployments to +[aur-dev.archlinux.org](https://aur-dev.archlinux.org). + +Services +-------- + +| Service | Host Binding | +|---------------------|-----------------| +| [ca](#ca) | | +| [cron](#cron) | | +| [mariadb](#mariadb) | 127.0.0.1:13306 | +| [git](#git) | 127.0.0.1:2222 | +| redis | 127.0.0.1:16379 | +| [php-fpm](#php-fpm) | 127.0.0.1:19000 | +| cgit-php | | +| [fastapi](#fastapi) | 127.0.0.1:18000 | +| cgit-fastapi | | +| [nginx](#nginx) (fastapi) | 127.0.0.1:8444 | +| [nginx](#nginx) (php) | 127.0.0.1:8443 | + +There are more services which have not been referred to here; +the services listed above encompass all notable services. Some +services have their own section, defined below, which lie down +specifics. + +#### ca + +The _ca_ service provides a certificate authority driven by `step-ca`. +When no certificates can be found, the ca services self-signs a new +root ca certificate and a localhost certificate to be used by nginx. + +The generated root ca certificate, after generation, will be located +at `./data/root_ca.crt` and can be imported into ca_certificates +anchors or browsers for SSL verification. + +#### cron + +The _cron_ service includes all scripts recommended in `doc/maintenance.txt`. + +#### mariadb + +- When used with the [default](#default) profile, a Docker-driven + mariadb service is used. +- When used with the [aur-dev](#aur-dev) profile, `MARIADB_SOCKET_DIR` + (defaulted to `/var/run/mysqld/`) can be defined to bind-mount a + host-driven mariadb socket to the container. + +#### git + +The _git_ service provides an ssh interface to a repository configured +to be used for the AUR. + +- When used with the [default](#default) profile, a Docker-driven + volume is used to manage the repository. +- When used with the [aur-dev](#aur-dev) profile, `GIT_DATA_DIR` + should be set to a directory found on the host to be used for + a bind-mounted repository. + +This service will perform setup in either case if the repository +is not yet initialized. + +#### php-fpm + +When running any services which use the _php-fpm_ backend or other +php-related services, users should define: + +- `AURWEB_PHP_PREFIX` + - Default: `https://localhost:8443` +- `AURWEB_SSHD_PREFIX` + - Default: `ssh://aur@localhost:2222` + +#### fastapi + +The _fastapi_ service hosts a `gunicorn`, `uvicorn` or `hypercorn` +asgi server. The backend and worker count can be configured using +the following variables: + +- `FASTAPI_BACKEND` + - Default: `uvicorn` + - Valid: `gunicorn`, `uvicorn`, `hypercorn` +- `FASTAPI_WORKERS` + - Default: 2 + +Additionally, when running any services which use the fastapi +backend or other fastapi-related services, users should define: + +- `AURWEB_FASTAPI_PREFIX` + - Default: `https://localhost:8444` +- `AURWEB_SSHD_PREFIX` + - Default: `ssh://aur@localhost:2222` + +#### nginx + +The _nginx_ service binds to two host endpoints: 127.0.0.1:8444 (fastapi) +and 127.0.0.1:8443 (php). Each instance is available over the `https` +protocol as noted in the table below. + +| Impl | Host Binding | URL | +|--------|----------------|------------------------| +| Python | 127.0.0.1:8444 | https://localhost:8444 | +| PHP | 127.0.0.1:8443 | https://localhost:8443 | + +When running this service, the following variables should be defined: + +- `AURWEB_FASTAPI_PREFIX` + - Default: `https://localhost:8444` +- `AURWEB_PHP_PREFIX` + - Default: `https://localhost:8443` +- `AURWEB_SSHD_PREFIX` + - Default: `ssh://aur@localhost:2222`