Improve documentation

Author: codedmonkey

contributing.md

@@ -0,0 +1,46 @@
+# Contributing to Dirigent
+
+Dirigent is an open-source project, contributions of all kind are welcome, including
+[financial contributions][codedmonkey-sponsor].
+
+## Running Dirigent locally
+
+To run Dirigent locally, follow the [Running from source code][dirigent-docs-install-source] guide in the documentation,
+up to the *Configure services* section.
+
+Additional requirements:
+
+- Symfony binary
+- Docker
+
+```shell
+# Optionally, copy the example Docker Compose configuration override file
+cp compose.override.example.yaml composer.override.yaml
+
+# Start Docker services
+docker compose up -d
+
+# Start Symfony local server
+symfony server:start -d
+```
+
+## Lint & test your code
+
+### Running PHPUnit tests
+
+Before running the tests, make sure the testing database is ready:
+
+```shell
+symfony console --env=test doctrine:database:create --if-not-exists
+symfony console --env=test doctrine:schema:update --force
+symfony console --env=test doctrine:fixtures:load --no-interaction
+```
+
+Run the PHPUnit tests:
+
+```shell
+symfony run bin/phpunit
+```
+
+[codedmonkey-sponsor]: https://www.codedmonkey.com/sponsor?project=dirigent
+[dirigent-docs-install-source]: https://dirigent.dev/docs/installation/source

docs/automatic-package-updates.md

@@ -1,8 +1,14 @@
 ---
-sidebar_position: 4
+sidebar_position: 30
 ---
 
-# Automatic Package Updates
+# Automatic package updates
+
+:::note
+
+This page is a stub.
+
+:::
 
 There are currently two ways to automatically update the packages in Dirigent:
 

docs/configuration-reference.md

@@ -1,8 +1,39 @@
 ---
+sidebar_label: Configuration reference
 sidebar_position: 99
 ---
 
-# Dirigent Configuration Reference
+# Dirigent configuration reference
+
+Dirigent uses the [Symfony][symfony] framework under the hood. Refer to the [Symfony documentation][symfony-docs-config]
+to learn how the configuration system works.
+
+When using the standalone image, any JSON or YAML file located directly in the `/srv/config` directory will be loaded
+as a Symfony configuration file.
+
+## Example configuration
+
+```yaml
+# dirigent.yaml
+dirigent:
+  title: 'My Dirigent'
+  slug: null
+  security:
+    public: false
+    registration: false
+  # not supported by the standalone image
+  #storage:
+  #  path: '%kernel.project_dir%/storage'
+  packages:
+    dynamic_updates: true
+    dynamic_update_delay: 'PT4H'
+    periodic_updates: true
+    periodic_update_interval: 'P1W'
+  dist_mirroring:
+    enabled: false
+    preferred: true
+    dev_packages: false
+```
 
 ## dirigent (root)
 
@@ -88,26 +119,6 @@ Whether to enable or disable distribution mirroring
 
 ### dev_packages
 
-## Example configuration
-
-```yaml
-dirigent:
-    title: My Dirigent
-    slug: my-dirigent
-    security:
-        public: false
-        registration: false
-    storage:
-        path: '%kernel.project_dir%/storage'
-    packages:
-        dynamic_updates: true
-        dynamic_update_delay: true
-        periodic_updates: true
-        periodic_update_interval: true
-    dist_mirroring:
-        enabled: true
-        preferred: true
-        dev_packages: false
-```
-
 [iso-8601-durations]: https://en.wikipedia.org/wiki/ISO_8601#Durations
+[symfony]: https://symfony.com
+[symfony-docs-config]: https://symfony.com/doc/current/configuration.html

docs/dist-mirroring.md

@@ -1,8 +1,14 @@
 ---
-sidebar_position: 5
+sidebar_position: 31
 ---
 
-# Dist Mirroring
+# Dist mirroring
+
+:::note
+
+This page is a stub.
+
+:::
 
 It's possible to mirror distributions of packages in Dirigent.
 

docs/getting-started.md

@@ -1,8 +1,9 @@
 ---
-sidebar_position: 3
+sidebar_label: Getting started
+sidebar_position: 20
 ---
 
-# Getting Started with Dirigent
+# Getting started with Dirigent
 
 Make sure you've followed the [installation][docs-install] guide before continuing.
 
@@ -11,17 +12,19 @@ Make sure you've followed the [installation][docs-install] guide before continui
 When accessing the login page of Dirigent for the first time, you'll be redirected to the registration page (even if
 registration is disabled). The first account created automatically gets an Owner role in the application.
 
-## Mirror public packages
+## Mirror public packages (packagist.org)
 
 After installing Dirigent, the [Packagist registry][packagist] is added as an external registry which makes it possible
 to mirror public packages. Dirigent is initially configured to only mirror packages explicitly added by an
 administrator.
 
-To enable mirroring of public packages on request, (as an administrator) open the "Registries" page, locate the
+To enable mirroring of public packages on request, open the "Registries" page (as an administrator), locate the
 Packagist registry, click the three dots and click "Edit". Find the "Package Mirroring" option and select "Automatically
 mirror packages on request". Save the registry for the changes to take effect.
 
-## Add packages
+## Read the documentation
 
-[docs-install]: install.md
+The usage and administration documentation is included in the application.
+
+[docs-install]: installation/readme.md
 [packagist]: https://packagist.org

docs/install.md

@@ -0,0 +1,2 @@
+label: Installation
+position: 10

docs/installation/_category_.yaml

@@ -0,0 +1,32 @@
+---
+sidebar_label: Docker Compose
+sidebar_position: 2
+---
+
+# Install Dirigent using Docker Compose
+
+:::note
+
+This page is a stub.
+
+:::
+
+## Example configuration file
+
+```yaml
+services:
+  database:
+    image: postgres:${POSTGRES_VERSION:-16}-alpine
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB:-dirigent}
+      # You should definitely change the password
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-!ChangeMe!}
+      POSTGRES_USER: ${POSTGRES_USER:-dirigent}
+    healthcheck:
+      test: ["CMD", "pg_isready"]
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+    volumes:
+      - ./postgres-data:/var/lib/postgresql/data:rw
+```

docs/installation/docker-compose.md

@@ -0,0 +1,104 @@
+---
+sidebar_label: Standalone Docker image
+sidebar_position: 1
+---
+
+# Install Dirigent using the standalone Docker image
+
+The easiest way to install Dirigent is by using our standalone Docker images, which bundle all services required for
+Dirigent into one, including a web server, database and a background worker. The standalone Docker images are available
+[on GitHub][github-docker-images].
+
+## Examples
+
+### Docker command
+
+```bash
+docker volume create dirigent-data
+
+docker container run -d \
+  --name dirigent \
+  -p "7015:7015" \
+  -v /path/to/dirigent/config:/srv/config \
+  -v dirigent-data:/srv/data \
+  ghcr.io/codedmonkey/dirigent:0.3
+```
+
+### Docker Compose configuration
+
+```yaml
+services:
+  dirigent:
+    image: ghcr.io/codedmonkey/dirigent:0.3
+    ports:
+      - "7015:7015"
+    volumes:
+      - ./config:/srv/config
+      - data:/srv/data
+
+volumes:
+  data:
+```
+
+## Volumes
+
+Both the `/srv/config` and `/srv/data` directories are configured as volumes, both need to be retained as the config
+directory contains encryption keys for sensitive data so make sure to mount it. It's recommend to store the
+configuration and data in separate locations, see our [security guide](../security.md) for more information.
+
+## Configuring Dirigent in the image
+
+When booting from the Docker image, Dirigent will look for custom configuration in the `/srv/config` directory. Make
+sure to mount it in the container as a volume, in the example Docker Compose configuration it's mounted from the
+`config/` directory located in your Docker Compose project.
+
+Create a file in the config directory called `dirigent.yaml` and add the following contents:
+
+```yaml
+dirigent:
+  title: My Dirigent
+  slug: my-dirigent
+  security:
+    public: false # Only enable public access if your instance is located behind a firewall
+    registration: false # Only enable registration if your instance is located behind a firewall
+```
+
+For a complete list of configuration options, see the [Configuration Reference][docs-configuration-reference].
+
+## Running the image
+
+After following the steps above you're ready to boot the image, so run the Docker command to start your
+container.
+
+By default, Dirigent is exposed on port `7015` so go to `http://localhost:7015` in your browser to access your
+Dirigent installation.
+
+_Note that Composer requires registries to use https by default._
+
+Now that you've installed Dirigent on your system, it's time to [get started][docs-getting-started]!
+
+## Building the standalone Docker image
+
+To build the standalone Docker image, clone [the Dirigent repository][github] and checkout the version or
+commit you want to build. Simply run the `docker build` command inside the repository to build the image.
+
+```shell
+git clone https://github.com/codedmonkey/dirigent.git
+cd dirigent
+git checkout v0.3.1
+docker build -t dirigent-standalone .
+```
+
+### Change UID and GID
+
+The standalone Docker image runs as user `1000:1000`. To run the image with a different UID or GID, you can pass both
+a `UID` and `GID` build argument to the `docker build` command.
+
+```shell
+docker build -t dirigent-standalone --build-arg UID=1011 --build-arg GID=1110 .
+```
+
+[docs-configuration-reference]: ../configuration-reference.md
+[docs-getting-started]: ../getting-started.md
+[github]: https://github.com/codedmonkey/dirigent
+[github-docker-images]: https://github.com/codedmonkey/dirigent/pkgs/container/dirigent