feat: docker compose deployment gudie + content adjustments (#9)

* feat: docker compose deployment guide + minor language changes

* fix: add volumes to initial deployment examples

* fix: update port description for deployment and add run commands for compose

* fix: formatting for compose deployment section

* fix: integrate review, update docker-compose deployment section

* fix: fix port mapping for standalone ui component

src/.vitepress/config.ts

@@ -101,6 +101,7 @@ export default defineConfig({
                     items: [
                         {text: 'Bare Metal', link: '/guide/deployment/bare-metal'},
                         {text: 'Docker', link: '/guide/deployment/docker'},
+                        {text: 'Docker Compose', link: '/guide/deployment/docker-compose'},
                     ]
                 },
             ],

src/getting-started/guides.md

@@ -1,7 +1,6 @@
 # Guides
-The subsequent guides are separated into two distinct categories depending on the user's usage intention.
-
-The following sections are available:
+Different user guides are provided depending on the user's usage intention. The following
+section provides an overview of the available guides.
 
 ## User Guide
 A user intends to access & manage resources (user, roles, permissions, ...) via the user interface.
@@ -10,7 +9,7 @@ As a user, you can view the following guide for further information.
 Read more [here](./../guide/user/index).
 
 ## Deployment Guide
-The deployment guide allows you to deploy Authup on **bare metal** or via **Docker** and provides 
+The deployment guide allows you to deploy Authup on different targets and provides 
 step-by-step instructions for doing so. 
 It also shows how to set up Authup with different database systems, Redis and other systems.
 

src/getting-started/index.md

@@ -1,10 +1,20 @@
 # What is Authup?
 
-Authup is an authentication & authorization system.
-It can be used as a headless system and can be provided with its own user interface.
-Otherwise, the supplied user interface can be used.
+Authup is an easy to use yet powerful authentication & authorization system. It's modular design allow you to only
+deploy the parts you need for your application and scale the system precisely as demands grow. You could for example run 
+multiple instances of the REST API along a single instance of the UI and use a load balancer to distribute the load.
+
+It comes with a fully featured admin panel giving you access to it's powerful REST API for user and permission
+management via a beautiful UI.
+
+Or it can be used as a headless system for which you may or may not implement your own user interface (when
+using [Vue JS](https://vuejs.org/) you can choose from pre-built components for you own application).
+
+Authup requires no external services and can be deployed on any system that
+supports [Node.js](https://nodejs.org/en/) but it can
+be configured to use external databases like [PostgreSQL](https://www.postgresql.org/)
+and [MySQL](https://www.mysql.com/) or [Redis](https://redis.io/) for caching.
 
-It can be run with different database drivers like sqlite, postgres & mysql.
 
 ::: warning **Important NOTE**
 The guide is under construction ☂ at the moment. So please stay patient or contribute to it, till it covers all parts ⭐.

src/guide/deployment/bare-metal.md

@@ -1,13 +1,14 @@
-# Instructions
+# Introduction
 
-This section will help to spin up Authup on the **host** system.
+This section will help you to spin up Authup directly on the **host** system.
 
 ## Requirements
 The following guide is based on some shared assumptions:
 
 - NodeJs `v16` (minimum)
 - Min. `2` cores
 - Min. `5G` hard disk
+- Up to two available ports (default: `3000` and `3001`)
 
 ## Step. 1: Create a new project
 

src/guide/deployment/configuration-api-database.md

@@ -1,10 +1,8 @@
 # Database
 
 By default, the database is run with `SQLite`,
-but `MySQL`(**recommended**) or `Postgres`(**recommended**) should be used for the following reasons.
-
-Postgres and MySQL are preferred over SQLite for their superior performance,
-scalability and advanced features such as built-in replication.
+but for a production environment we recommend using `MySQL` or `Postgres` since they provide
+superior performance, scalability and advanced features such as built-in replication.
 
 ## MySQL
 

src/guide/deployment/configuration.md

@@ -3,8 +3,8 @@
 The configuration is similar for both Bare Metal and Docker variants. 
 In both cases, configuration can be done via configuration file or environment variables.
 
-In general **no** configuration file is required at all!
-All options have either default values or are generated automatically 🔥.
+In general **no** configuration file is required!
+All options have either sensible default values or are generated automatically 🔥.
 
 Due to the fact that authup consists of several components, they can be configured either globally or individually.
 

src/guide/deployment/docker-compose.md

@@ -0,0 +1,215 @@
+# Introduction
+
+This section will help you set up Authup in a **docker-compose** environment.
+
+## Requirements
+The following guide is based on some shared assumptions:
+
+- Min. `2` cores
+- Min. `5G` hard disk
+- Docker `v20.x` is [installed](https://docs.docker.com/get-docker/)
+- Up to two available ports on the host system if you want to map the services to your local machine (default: `3000` and `3001`)
+- This guide assumes [Compose v2](https://docs.docker.com/compose/compose-file/)
+
+
+
+## Quick Start
+
+This section contains multiple examples for how to deploy and configure authup using docker-compose. The different 
+examples show how to configure authup using the options described in the [configuration](./configuration) section. Simply
+paste and modify the example you want to use into a `docker-compose.yml` file.
+
+The following example shows a sensible default configuration for getting started with Authup. This will start the REST API as well as the UI from
+the same container and forward them to the ports `3001` and `3000` respectively on the local machine.
+
+```yaml
+version: '3.8'
+
+volumes:
+    authup:
+
+services:
+  authup:
+    image: ghcr.io/authup/authup:latest
+    container_name: authup
+    restart: unless-stopped
+    volumes:
+      # Docker managed volume
+      - authup:/usr/src/writable
+      # storage in mounted volume
+      #- ./writable:/usr/src/writable
+    ports:
+      - "3000:3000"
+      - "3001:3001"
+    command: cli start
+
+```
+
+Then start the service using the following command:
+
+```bash
+docker compose up -d
+```
+
+and check the logs using:
+
+```bash
+docker compose logs -f
+```
+
+## Configuration
+
+The following examples show different ways to configure and use the Authup service using docker-compose. For more general
+information about how to configure Authup, see the [configuration](./configuration) section.
+
+::: warning **Warning**
+When starting more than one service from the same container (such as in the quick start example) you can not use
+environment variable to configure the services. This is because of potential conflicts between the different services.
+
+Instead, you should use a mounted configuration file to configure the services. See the [configuration file](#configuration-file) 
+section for more information.
+:::
+
+
+### Environment variables
+
+The following example shows how to configure the Authup service using environment variables. This will start only the
+REST API and forward it to the port `3000` on the local machine.
+
+```yaml
+version: '3.8'
+
+volumes:
+    authup:
+
+services:
+  authup:
+    image: ghcr.io/authup/authup:latest
+    container_name: authup
+    restart: unless-stopped
+    volumes:
+      - authup:/usr/src/writable
+    ports:
+      - "3000:3000"
+    environment:
+        - ADMIN_USERNAME=test
+        - ADMIN_PASSWORD=test-password
+```
+
+
+### Configuration file
+
+This example shows how to start both services from the same container with the API being configured with non-default
+values via a mounted configuration file.
+
+Create a directory `writable` in the same directory as the `docker-compose.yml` file.
+```bash
+mkdir writable
+cd writable
+```
+Then create a file called `authup.api.conf` and store it in the `writable` directory. Paste the following content into 
+the file which will configure the admin user for the API service:
+
+```dotenv
+adminUsername=test
+adminPassword=test-password
+```
+
+In the following compose file example you can see that the `writable` directory containing the `authup.api.conf` 
+configuration file is mounted into the container under `/usr/src/writable` which is the default location for 
+configuration files.
+
+```yaml
+version: '3.8'
+
+volumes:
+  authup:
+
+services:
+  authup:
+    image: ghcr.io/authup/authup:latest
+    container_name: authup
+    restart: unless-stopped
+    volumes:
+      - ./writable:/usr/src/writable
+    ports:
+      - "3000:3000"
+      - "3001:3001"
+    command: cli start
+
+```
+
+
+### Multiple services
+
+This shows an example of how to run authup alongside other services (postgres & redis) and connect to them. It also shows how to split 
+Authup into multiple services running the UI and API in separate containers.
+
+Configuration via environment variables is possible in this configuration since both service are running in separate containers.
+
+```yaml
+version: '3.8'
+
+volumes:
+    authup_data:
+    postgres_data:
+    redis_data:
+
+services:
+    authup-api:
+        image: ghcr.io/authup/authup:latest
+        container_name: authup-api
+        restart: unless-stopped
+        volumes:
+            - authup_data:/usr/src/writable
+        ports:
+            - "3001:3000"
+        depends_on:
+            - postgres
+            - redis
+        environment:
+            - DB_TYPE=postgres
+            - DB_HOST=postgres
+            - DB_PORT=5432
+            - DB_USERNAME=postgres
+            - DB_PASSWORD=postgres
+            - DB_DATABASE=postgres
+            - REDIS_URL=redis://redis:6379
+
+    authup-ui:
+        image: ghcr.io/authup/authup:latest
+        container_name: authup-ui
+        restart: unless-stopped
+        depends_on:
+          - authup-api
+        ports:
+            - "3000:3000"
+        command: ui start
+
+    postgres:
+        image: postgres:14
+        container_name: postgres
+        restart: unless-stopped
+        volumes:
+            - postgres_data:/var/lib/postgresql/data
+        environment:
+            - POSTGRES_PASSWORD=postgres
+            - POSTGRES_USER=postgres
+            - POSTGRES_DB=postgres
+
+    redis:
+        image: redis:latest
+        container_name: redis
+        restart: unless-stopped
+        volumes:
+            - redis_data:/data
+
+```
+
+## Troubleshooting
+### Authup not reachable for redirect in other services
+If you would like to access the Authup instance and your operations require a redirect to the Authup instance, you need to
+set the `PUBLIC_URL` environment variable to the service name and port of the Authup service (i.e. `authup:3000`). This will
+allow the compose network to resolve the service name to the correct IP address.
+
+

src/guide/deployment/docker.md

@@ -1,14 +1,14 @@
-# Instructions
+# Introduction
 
-This section will help to spin up Authup in a **docker** container environment.
+This section will help you spin up Authup as a **docker** container.
 
 ## Requirements
 The following guide is based on some shared assumptions:
 
-- OS `debian` or `ubuntu`
-- Docker `v20.x` is installed
+- Docker `v20.x` is [installed](https://docs.docker.com/get-docker/)
 - Min. `2` cores
 - Min. `5G` hard disk
+- Up to two available ports on the host system if you want to map the services to your local machine (default: `3000` and `3001`)
 
 
 ## Step. 1: Create a new project

src/guide/deployment/index.md

@@ -2,10 +2,11 @@
 
 The Authup Deployment Guide is a comprehensive resource for users looking to deploy Authup on various targets 🚀: 
 
-- **`Bare Metal`**: Bare Metal is the term used to describe running Authup on the host system with NodeJs.
-- **`Docker`**: Docker is the term used to describe running Authup in a virtual environment using Docker (**recommended**).
+- **`Bare Metal`**: [Bare Metal](./bare-metal) deploy Authup directly on the host system using NodeJs.
+- **`Docker`**: [Docker](./docker) deploy authup as a standalone docker container (**recommended**).
+- **`Docker Compose`**: [Docker Compose](./docker-compose) integrate Authup into a docker-compose environment.
 
-In the beginning it is shown how Authup is configured and in particular how individual applications of it are configured.
+Following this guide you will first learn how to configure your Authup instance and how to then deploy it on your chosen target.
 
-Whether you are a seasoned developer or new to deployment, the Authup Deployment Guide is an essential resource for anyone looking to deploy Authup. 
+Whether you are a seasoned dev-ops engineer or new to deployment, the Authup Deployment Guide is an essential resource for anyone looking to deploy Authup. 
 With step-by-step 📝 instructions, helpful tips and tricks, and links to additional resources, this guide will help you to deploy Authup successfully on your chosen target.