Introduction

What is this project?

This projects tries to deliver an easy and fast solution to setup your project and start developing after. The Idea is to handle the complete configuration and authentication and be easy to configure without previous knowledge.

What does this project deliver?

A 3 Layer architecture
Production, local and optionally a dev environment
Authentication and User Management professionally handled by Authelia and lldap
https communication provided by traefik and LetsEntrypt
choose you own technologies for Front- and Backend

What type of project is this for?

This project is meant for prototypes and applications for up to 5000 monthly active Users.

Because it is already dockerized, the path is paved to move to a bigger scaling.

Get Started

To use the project you will have to complete these steps in the correct order.

Check and apply prerequisites

A Server to run on
The Server needs docker installed, look up the Docker documentation for installation guides
And you need a domain for certificates. For the intended configuration you will need three,
you can name the subdomains whatever you want. This is an example:
- app.yourdomain.com -> for the application, used by the visitor
- auth.yourdomain.com -> for authelia
- ldap.yourdomain.com -> for the usermanagement
They should all point to the Server IP with an A Record
An E-Mail SMTP Server.
And for local development Docker Desktop is recommended

Choose Your Wanted Technologies

Create an Empty Repository

You can choose any Git Platform, but for GitHub there are already simple pipelines included. Then navigate to your Repository


                git clone https://github.com/my-name/my-repo.git


                cd my-repo

Copy the latest Release in your Repository

Windows Powershell


                Invoke-WebRequest -Uri "https://github.com/LReg/AutheliaBlueprint/archive/refs/tags/0.0.9.zip" -OutFile "AutheliaBlueprint.zip"; Expand-Archive -Path "AutheliaBlueprint.zip" -DestinationPath "temp" -Force; Move-Item -Path "temp/*/*" -Destination "."; Remove-Item -Recurse -Force "temp"; Remove-Item "AutheliaBlueprint.zip"

Unix (with curl)


                curl -L -o AutheliaBlueprint.zip https://github.com/LReg/AutheliaBlueprint/archive/refs/tags/0.0.9.zip && unzip AutheliaBlueprint.zip -d temp && shopt -s dotglob && mv temp/*/* ./ && rm -r temp AutheliaBlueprint.zip

Give execution rights to script


                chmod +x ./use.sh

Decide on Technologies from these Options

Frontend

angular
vue

Backend

go-fiber
express

Execute script with wanted Technologies

Use the exact wording from the list, because it needs to find a folder with that name.


                ./use.sh [backend-technology] [frontend-technology]

Push your changes to you repository


                git add .


                git commit -m "init"


                git push

Setup server environment

Disclaimer

This Guide uses a build on server and then run approach. For now this blueprint does not feature any docker registry involvement.

Log into your server via ssh


                ssh root@your-server-ip

Create a technical user

Remember to replace my-technical-user with your desired username. And store your password in a safe place.


                adduser my-technical-user


                usermod -aG sudo my-technical-user


                usermod -aG docker my-technical-user


                su - my-technical-user

Gain Access to Repository

If your repository is public you can skip this step. Else it is recommended to use an ssh key.

Here Github explains this process.

Clone your Repository


                git clone git@github.com:username/repo.git


                cd my-repo

Give execution rights to setup script


                chmod +x ./setup.sh

Execute setup script with init option

This will create your .env file and generate all secrets you need.


                sudo ./setup.sh init path/to/docker/volumes

Configure .env file OR set values as pipeline secrets

If you don't want secrets or configuration on your server, you can deliver all data via Pipeline secrets. It is explained here.

But let's first focus on the .env. And if you want to move it to the pipeline it is all explained there.

Open the .env file with your favorite editor


                vim .env

Fill in all values except secrets

Every secret you see is generated by scripts. You dont't need to change them.

General

APP_NAME=YourAppName : Used to avoid nameconflics, added for example to container names
DOCKER_VOLUME_PATH : where the app stores the docker volumes. Might be a good idea to not store in the repo folder

# example for https://app.yourdomain.com
- DOMAIN=yourdomain
- D_ENDING=com : Domain ending

- APP_SUBDOMAIN=app : Subdomain for your app -> https://app.yourdomain.com
- AUTH_SUBDOMAIN=auth : Subdomain for authelia -> https://auth.yourdomain.com
- LDAP_SUBDOMAIN=ldap : Subdomain for you ldap (user management) -> https://ldap.yourdomain.com

- CALLBACK_PATH=home : The path where the frontend will redirect to after login (must fit exactly with that you program in the frontend)
                        "home" is the default for all preconfigured frontends

Traefik

# mainly to avoid name conflicts
# In case you already have a traefik container running you can change everything except the email to the running traefik instance you have.
- TRAEFIK_NETWORK=YourTraefikNetwork
- TRAEFIK_CERT_RESOLVER=YourCertResolver
- TRAEFIK_ENTRYPOINT=YourHttpsEntryPoint
- TRAEFIK_EMAIL=YourEmail@gmail.com

Authelia

- AUTHELIA_RESET_PASSWORD_SECRET=super-secret-password : **generate secret**
- AUTHELIA_SESSION_REDIS_PASSWORD=redis-password : **generate secret**
- AUTHELIA_SESSION_SECRET=super-secret-session : **generate secret**

LLDAP

- LLDAP_JWT_SECRET=super-secret-jwt : **generate secret**
- LLDAP_KEY_SEED=super-secret-seed : **generate secret**
- LLDAP_USERNAME=authelia : these are the credentials for the lldap user. You will need to add a user to lldap with these.
- LLDAP_PASSWORD=secret-password : **generate secret**

Postgres (Authelia Storage)

- POSTGRES_PASSWORD=super-secret-password : **generate secret**
- POSTGRES_ENCRYPTION_KEY=super-secret-encryption-key : **generate secret**

OIDC

# these can left on the default values. But you can change them if you want.
- OIDC_HMAC_SECRET=super-secret-hmac : **generate secret**
- OIDC_CLIENT_ID=your-client-id
- OIDC_CLIENT_NAME=your-client-name

Database

# these can left on the default values. But you can change them if you want.
- DB_ROOT_USERNAME=root
- DB_ROOT_PASSWORD=root-password : **generate secret**
- DB_USERNAME=db-username
- DB_PASSWORD=db-password : **generate secret**

Mail SMTP

- SMTP_USERNAME=user
- SMTP_PASSWORD=password : **generate secret**
- SMTP_HOST=smtp://smtp.gmail.com:587 : don't forget to use protocol and port
- SMTP_SENDER=mail@app.de

# In case you selfhost your mailserver there might be some problems with the certs. Then you can experiment with these values.
# When you have no problems leave them on false.
- SMTP_DISABLE_REQUIRE_TLS=false
- SMTP_DISABLE_STARTTLS=false
- SMTP_SKIP_TLS_VERIFY=false

Rerun setup script to write template files

The configured variables need to be written to the configuration files from Authelia and the Database. You do not need init anymore, because you already did that. The secrets are filled in in your .env file.


                sudo ./setup.sh

Any time you change the .env file you will need to rerun this script. You will probably need sudo because the docker container volumes are owned by root.

Start your services

There is a script for easier starting and stopping of the services.

Traefik

If you already have a traefik instance running you can skip this step. Make sure you put in the correct names in the .env file.


                ./docker-cli.sh up traefik

Error

You might get an error Message because the network Traefik wants to use does not exist like: "network YourTraefikNetwork declared as external, but could not be found" you can react with creating the network:


                docker network create YourTraefikNetwork

Authelia and related stuff


                ./docker-cli.sh up auth

After the first startup

On the first startup the lldap user that authelia wants to use will not exist. This will lead to the authelia container to be unhealthy and restarting.
So you will need to login to lldap on you ldap.youdomain.com (LDAP_SUBDOMAIN) and login with admin:password and then
create the user you defined in your .env File.
The secrets can be found in the variables: LLDAP_USERNAME and LLDAP_PASSWORD. The user needs to have the group ldap_password_manager added after. And of course change the admin password. For further information look into the lldap Repo, very good project.

Database


                ./docker-cli.sh up db

Backend


                ./docker-cli.sh up backend

Frontend


                ./docker-cli.sh up frontend

Test if everything works

You can visit app.youdomain.com

Setup local environment

The idea is that you will use the authelia instance from your server environment. This way you only need database, frontend and backend locally.

Clone your repository


                git clone git@github.com:username/repo.git


                cd my-repo

DB and Backend

For the database and backend it is planned to run them with docker locally. This makes spreading of environmentvariables easy. The .env file you need for that is already provided. If you rather dont't want to run the backend with docker it is usually not hard to provide the environment variables in another way. You can lookup the needed ones in the docker-compose file: docker/composeFiles/local.docker-compose.yml

Configuration


                cp .env.local .env

In this file you will need to change two values:

- AUTH_DOMAIN=auth.yourdomain.com
- OIDC_CLIENT_ID=your-client-id

These need to have the same value as in the .env file on your server.

Starting the containers


                chmod +x ./docker-cli.sh
                ./docker-cli.sh up db local
                ./docker-cli.sh up backend local

Frontend

Running the frontend locally in a docker container usually does not make sense. So you will need to run it with a classic approach like npm.

Configuration

The different frontend Frameworks treat their environment variable delivery differently. But what stays the same is that you will need to change the AuthDomain and the OIDCClientId. I will provide a short explanation for the different frontend technologies.

Angular

Change the values in frontend/src/environments/environment.ts

Vue


                cp frontend/.env.example frontend/.env

Then change the values in frontend/.env

Start the application

Starting the applications also works different. For now all frontend technologies are npm based so the approach is the same.


                cd frontend
                npm install
                npm run start

Introduction

What is this project?

What does this project deliver?

What type of project is this for?

Get Started

Check and apply prerequisites

Choose Your Wanted Technologies

Create an Empty Repository

Copy the latest Release in your Repository

Windows Powershell

Unix (with curl)

Give execution rights to script

Decide on Technologies from these Options

Frontend

Backend

Execute script with wanted Technologies

Push your changes to you repository

Setup server environment

Log into your server via ssh

Create a technical user

Gain Access to Repository

Clone your Repository

Give execution rights to setup script

Execute setup script with init option

Configure .env file OR set values as pipeline secrets

Fill in all values except secrets

General

Traefik

Authelia

LLDAP

Postgres (Authelia Storage)

OIDC

Database

Mail SMTP

Rerun setup script to write template files

Start your services

Traefik

Error

Authelia and related stuff

After the first startup

Database

Backend

Frontend

Test if everything works

Setup local environment

Clone your repository

DB and Backend

Configuration

Starting the containers

Frontend

Configuration

Angular

Vue

Start the application

Pipeline configuration