From 5002e431197d12e9d13d7a052a2feda4f9f694d4 Mon Sep 17 00:00:00 2001 From: Michael Graf Date: Mon, 3 Apr 2023 10:14:54 +0200 Subject: [PATCH] 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 | 1 + src/getting-started/guides.md | 7 +- src/getting-started/index.md | 18 +- src/guide/deployment/bare-metal.md | 5 +- .../deployment/configuration-api-database.md | 6 +- src/guide/deployment/configuration.md | 4 +- src/guide/deployment/docker-compose.md | 215 ++++++++++++++++++ src/guide/deployment/docker.md | 8 +- src/guide/deployment/index.md | 9 +- 9 files changed, 249 insertions(+), 24 deletions(-) create mode 100644 src/guide/deployment/docker-compose.md diff --git a/src/.vitepress/config.ts b/src/.vitepress/config.ts index c71f447..f43b458 100644 --- a/src/.vitepress/config.ts +++ b/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'}, ] }, ], diff --git a/src/getting-started/guides.md b/src/getting-started/guides.md index 2d7b222..f376f2d 100644 --- a/src/getting-started/guides.md +++ b/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. diff --git a/src/getting-started/index.md b/src/getting-started/index.md index d52f571..ef6745d 100644 --- a/src/getting-started/index.md +++ b/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 ⭐. diff --git a/src/guide/deployment/bare-metal.md b/src/guide/deployment/bare-metal.md index cf0d79b..90be020 100644 --- a/src/guide/deployment/bare-metal.md +++ b/src/guide/deployment/bare-metal.md @@ -1,6 +1,6 @@ -# 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: @@ -8,6 +8,7 @@ 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 diff --git a/src/guide/deployment/configuration-api-database.md b/src/guide/deployment/configuration-api-database.md index 0a80ed8..23cdf85 100644 --- a/src/guide/deployment/configuration-api-database.md +++ b/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 diff --git a/src/guide/deployment/configuration.md b/src/guide/deployment/configuration.md index 1ab5c05..80407a4 100644 --- a/src/guide/deployment/configuration.md +++ b/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. diff --git a/src/guide/deployment/docker-compose.md b/src/guide/deployment/docker-compose.md new file mode 100644 index 0000000..115fbbc --- /dev/null +++ b/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. + + diff --git a/src/guide/deployment/docker.md b/src/guide/deployment/docker.md index 41ac4a7..772468b 100644 --- a/src/guide/deployment/docker.md +++ b/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 diff --git a/src/guide/deployment/index.md b/src/guide/deployment/index.md index 4f1735a..2f6d30e 100644 --- a/src/guide/deployment/index.md +++ b/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.