RPJosh
/
authelia
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Docker] Include docker-compose.yml examples to run Authelia (#642) 

* [Docker] Create Lite docker-compose.yml example

* [Docker] Update README.md with 3 compose bundles {Local,Lite,Full}

* [DOCS] Update Traefik2 proxy example

* [Docker] Create Local docker-compose.yml example

* [MISC] Update examples to utilise Traefik 2.2
This change enables global http -> https redirection.

* [Docker] Update Local compose to utilise loopback address

* [Docker] Drop compose version to 3.3 to cater for more distros

* [DOCS] Adjust Getting Started

* [Docker] Tweak Local bundle setup for OSX

* [Docker] Optimise setup.sh for Local bundle

* [Docker] Fix read-only mounting of user database

* [DOCS] Implement feedback for compose bundles

* [DOCS] Provide feedback on self-signed certificates

* [DOCS] Implement additional feedback for compose bundles

Co-authored-by: Clément Michaud <clement.michaud34@gmail.com>
pull/786/head
Amir Zarrinkafsh 2020-03-27 10:43:10 +11:00 committed by GitHub
parent 952764fcad
commit e843a52a04
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
17 changed files with 561 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
README.md
View File

@ -79,12 +79,20 @@ Docker or on top of [Kubernetes].
## Getting Started
You can start off with
You can start utilising Authelia with the provided `docker-compose` bundles:
git clone https://github.com/authelia/authelia.git && cd authelia
source bootstrap.sh
##### [Local](https://docs.authelia.com/getting-started)
The Local compose bundle is intended to test Authelia without worrying about configuration.
It's meant to be used for scenarios where the server is not be exposed to the internet.
Domains will be defined in the local hosts file and self-signed certificates will be utilised.
If you want to go further, please read [Getting Started](https://docs.authelia.com/getting-started).
##### [Lite](https://docs.authelia.com/deployment/deployment-lite)
The Lite compose bundle is intended for scenarios where the server will be exposed to the internet, domains and DNS will need to be setup accordingly and certificates will be generated through LetsEncrypt.
The Lite element refers to minimal external dependencies; File based user storage, SQLite based configuration storage. In this configuration, the service will not scale well.
##### [Full](https://docs.authelia.com/deployment/deployment-ha)
The Full compose bundle is intended for scenarios where the server will be exposed to the internet, domains and DNS will need to be setup accordingly and certificates will be generated through LetsEncrypt.
The Full element refers to a scalable setup which includes external dependencies; LDAP based user storage, Database based configuration storage (MariaDB, MySQL or Postgres).
## Deployment

65
compose/lite/configuration.yml 100644
View File

@ -0,0 +1,65 @@
###############################################################
# Authelia configuration #
###############################################################
host: 0.0.0.0
port: 9091
log_level: debug
# This secret can also be set using the env variables AUTHELIA_JWT_SECRET
jwt_secret: a_very_important_secret
default_redirection_url: https://public.example.com
totp:
issuer: authelia.com
#duo_api:
# hostname: api-123456789.example.com
# integration_key: ABCDEF
# # This secret can also be set using the env variables AUTHELIA_DUO_API_SECRET_KEY
# secret_key: 1234567890abcdefghifjkl
authentication_backend:
file:
path: /etc/authelia/users_database.yml
access_control:
default_policy: deny
rules:
# Rules applied to everyone
- domain: public.example.com
policy: bypass
- domain: traefik.example.com
policy: one_factor
- domain: secure.example.com
policy: two_factor
session:
name: authelia_session
# This secret can also be set using the env variables AUTHELIA_SESSION_SECRET
secret: unsecure_session_secret
expiration: 3600 # 1 hour
inactivity: 300 # 5 minutes
domain: example.com # Should match whatever your root protected domain is
redis:
host: redis
port: 6379
# This secret can also be set using the env variables AUTHELIA_SESSION_REDIS_PASSWORD
password: authelia
regulation:
max_retries: 3
find_time: 120
ban_time: 300
storage:
local:
path: /var/lib/authelia/db.sqlite3
notifier:
smtp:
username: test
# This secret can also be set using the env variables AUTHELIA_NOTIFIER_SMTP_PASSWORD
password: password
host: mail.example.com
port: 25
sender: admin@example.com

110
compose/lite/docker-compose.yml 100644
View File

@ -0,0 +1,110 @@
version: '3.3'
networks:
net:
driver: bridge
services:
authelia:
image: authelia/authelia
container_name: authelia
volumes:
- ./authelia:/var/lib/authelia
- ./configuration.yml:/etc/authelia/configuration.yml:ro
- ./users_database.yml:/etc/authelia/users_database.yml
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.authelia.rule=Host(`auth.example.com`)'
- 'traefik.http.routers.authelia.entrypoints=https'
- 'traefik.http.routers.authelia.tls=true'
- 'traefik.http.routers.authelia.tls.certresolver=letsencrypt'
- 'traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://auth.example.com'
- 'traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true'
expose:
- 9091
restart: unless-stopped
environment:
- TZ=Australia/Melbourne
redis:
image: redis:alpine
container_name: redis
volumes:
- ./redis:/data
networks:
- net
expose:
- 6379
restart: unless-stopped
environment:
- TZ=Australia/Melbourne
traefik:
image: traefik:v2.2
container_name: traefik
volumes:
- ./traefik/acme.json:/acme.json
- /var/run/docker.sock:/var/run/docker.sock
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.api.rule=Host(`traefik.example.com`)'
- 'traefik.http.routers.api.entrypoints=https'
- 'traefik.http.routers.api.service=api@internal'
- 'traefik.http.routers.api.tls=true'
- 'traefik.http.routers.api.tls.certresolver=letsencrypt'
- 'traefik.http.routers.api.middlewares=authelia@docker'
ports:
- 80:80
- 443:443
command:
- '--api'
- '--providers.docker=true'
- '--providers.docker.exposedByDefault=false'
- '--entrypoints.http=true'
- '--entrypoints.http.address=:80'
- '--entrypoints.http.http.redirections.entrypoint.to=https'
- '--entrypoints.http.http.redirections.entrypoint.scheme=https'
- '--entrypoints.https=true'
- '--entrypoints.https.address=:443'
- '--certificatesResolvers.letsencrypt.acme.email=your-email@your-domain.com'
- '--certificatesResolvers.letsencrypt.acme.storage=acme.json'
- '--certificatesResolvers.letsencrypt.acme.httpChallenge.entryPoint=http'
- '--log=true'
- '--log.level=DEBUG'
- '--log.filepath=/var/log/traefik.log'
secure:
image: containous/whoami
container_name: secure
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.secure.rule=Host(`secure.example.com`)'
- 'traefik.http.routers.secure.entrypoints=https'
- 'traefik.http.routers.secure.tls=true'
- 'traefik.http.routers.secure.tls.certresolver=letsencrypt'
- 'traefik.http.routers.secure.middlewares=authelia@docker'
expose:
- 80
restart: unless-stopped
public:
image: containous/whoami
container_name: public
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.public.rule=Host(`public.example.com`)'
- 'traefik.http.routers.public.entrypoints=https'
- 'traefik.http.routers.public.tls=true'
- 'traefik.http.routers.public.tls.certresolver=letsencrypt'
- 'traefik.http.routers.public.middlewares=authelia@docker'
expose:
- 80
restart: unless-stopped

14
compose/lite/users_database.yml 100644
View File

@ -0,0 +1,14 @@
###############################################################
# Users Database #
###############################################################
# This file can be used if you do not have an LDAP set up.
# List of users
users:
authelia:
password: "$6$rounds=50000$BpLnfgDsc2WD8F2q$Zis.ixdg9s/UOJYrs56b5QEZFiZECu0qZVNsIYxBaNJ7ucIL.nlxVCT5tqh8KHG8X4tlwCFm5r6NTOZZ5qRFN/" # Password is 'authelia'
email: authelia@authelia.com
groups:
- admins
- dev

45
compose/local/configuration.yml 100644
View File

@ -0,0 +1,45 @@
###############################################################
# Authelia configuration #
###############################################################
host: 0.0.0.0
port: 9091
log_level: debug
jwt_secret: a_very_important_secret
default_redirection_url: https://public.example.com
totp:
issuer: authelia.com
authentication_backend:
file:
path: /etc/authelia/users_database.yml
access_control:
default_policy: deny
rules:
- domain: public.example.com
policy: bypass
- domain: traefik.example.com
policy: one_factor
- domain: secure.example.com
policy: two_factor
session:
name: authelia_session
secret: unsecure_session_secret
expiration: 3600 # 1 hour
inactivity: 300 # 5 minutes
domain: example.com # Should match whatever your root protected domain is
regulation:
max_retries: 3
find_time: 120
ban_time: 300
storage:
local:
path: /var/lib/authelia/db.sqlite3
notifier:
filesystem:
filename: /var/lib/authelia/notification.txt

95
compose/local/docker-compose.yml 100644
View File

@ -0,0 +1,95 @@
version: '3.3'
networks:
net:
driver: bridge
services:
authelia:
image: authelia/authelia
container_name: authelia
volumes:
- ./authelia:/var/lib/authelia
- ./configuration.yml:/etc/authelia/configuration.yml:ro
- ./users_database.yml:/etc/authelia/users_database.yml
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.authelia.rule=Host(`authelia.example.com`)'
- 'traefik.http.routers.authelia.entrypoints=https'
- 'traefik.http.routers.authelia.tls=true'
- 'traefik.http.routers.authelia.tls.options=default'
- 'traefik.http.middlewares.authelia.forwardauth.address=http://authelia:9091/api/verify?rd=https://authelia.example.com'
- 'traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true'
expose:
- 9091
restart: unless-stopped
environment:
- TZ=Australia/Melbourne
traefik:
image: traefik:v2.2
container_name: traefik
volumes:
- ./traefik:/etc/traefik
- /var/run/docker.sock:/var/run/docker.sock
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.api.rule=Host(`traefik.example.com`)'
- 'traefik.http.routers.api.entrypoints=https'
- 'traefik.http.routers.api.service=api@internal'
- 'traefik.http.routers.api.tls=true'
- 'traefik.http.routers.api.tls.options=default'
- 'traefik.http.routers.api.middlewares=authelia@docker'
ports:
- 80:80
- 443:443
command:
- '--api'
- '--providers.docker=true'
- '--providers.docker.exposedByDefault=false'
- '--providers.file.filename=/etc/traefik/certificates.yml'
- '--entrypoints.http=true'
- '--entrypoints.http.address=:80'
- '--entrypoints.http.http.redirections.entrypoint.to=https'
- '--entrypoints.http.http.redirections.entrypoint.scheme=https'
- '--entrypoints.https=true'
- '--entrypoints.https.address=:443'
- '--log=true'
- '--log.level=DEBUG'
- '--log.filepath=/var/log/traefik.log'
secure:
image: containous/whoami
container_name: secure
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.secure.rule=Host(`secure.example.com`)'
- 'traefik.http.routers.secure.entrypoints=https'
- 'traefik.http.routers.secure.tls=true'
- 'traefik.http.routers.secure.tls.options=default'
- 'traefik.http.routers.secure.middlewares=authelia@docker'
expose:
- 80
restart: unless-stopped
public:
image: containous/whoami
container_name: public
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.public.rule=Host(`public.example.com`)'
- 'traefik.http.routers.public.entrypoints=https'
- 'traefik.http.routers.public.tls=true'
- 'traefik.http.routers.public.tls.options=default'
- 'traefik.http.routers.public.middlewares=authelia@docker'
expose:
- 80
restart: unless-stopped

94
compose/local/setup.sh 100755
View File

@ -0,0 +1,94 @@
#!/bin/bash
username(){
read -ep "Enter your username for Authelia: " USERNAME
}
password(){
read -esp "Enter a password for $USERNAME: " PASSWORD
}
echo "Checking for pre-requisites"
if [[ ! -x "$(command -v docker)" ]]; then
echo "You must install Docker on your machine";
return
fi
if [[ ! -x "$(command -v docker-compose)" ]]; then
echo "You must install Docker Compose on your machine";
return
fi
echo "Pulling Authelia docker image for setup"
docker pull authelia/authelia > /dev/null
read -ep "What root domain would you like to protect? (default/no selection is example.com): " DOMAIN
if [[ $DOMAIN == "" ]]; then
DOMAIN="example.com"
fi
MODIFIED=$(cat /etc/hosts | grep $DOMAIN && echo true || echo false)
if [[ $MODIFIED == "false" ]]; then
echo "\
127.0.0.1 authelia.$DOMAIN
127.0.0.1 public.$DOMAIN
127.0.0.1 traefik.$DOMAIN
127.0.0.1 secure.$DOMAIN" >> /etc/hosts
fi
echo "Generating SSL certificate for *.$DOMAIN"
docker run -a stdout -v $PWD/traefik/certs:/tmp/certs authelia/authelia authelia certificates generate --host *.$DOMAIN --dir /tmp/certs/ > /dev/null
if [[ $DOMAIN != "example.com" ]]; then
if [[ $(uname) == "Darwin" ]]; then
sed -i '' "s/example.com/$DOMAIN/g" {docker-compose.yml,configuration.yml}
else
sed -i "s/example.com/$DOMAIN/g" {docker-compose.yml,configuration.yml}
fi
fi
username
if [[ $USERNAME != "" ]]; then
if [[ $(uname) == "Darwin" ]]; then
sed -i '' "s/<USERNAME>/$USERNAME/g" users_database.yml
else
sed -i "s/<USERNAME>/$USERNAME/g" users_database.yml
fi
else
echo "Username cannot be empty"
username
fi
password
if [[ $PASSWORD != "" ]]; then
PASSWORD=$(docker run authelia/authelia authelia hash-password $PASSWORD | sed 's/Password hash: //g')
if [[ $(uname) == "Darwin" ]]; then
sed -i '' "s/<PASSWORD>/$(echo $PASSWORD | sed -e 's/[\/&]/\\&/g')/g" users_database.yml
else
sed -i "s/<PASSWORD>/$(echo $PASSWORD | sed -e 's/[\/&]/\\&/g')/g" users_database.yml
fi
else
echo "Password cannot be empty"
password
fi
docker-compose up -d
cat << EOF
Setup completed successfully.
You can now visit the following locations:
- https://public.$DOMAIN - Bypasses Authelia
- https://traefik.$DOMAIN - Secured with Authelia one-factor authentication
- https://secure.$DOMAIN - Secured with Authelia two-factor authentication (see note below)
You will need to authorize the self-signed certificate upon visiting each domain.
To visit https://secure.$DOMAIN you will need to register a device for second factor authentication and confirm by clicking on a link sent by email. Since this is a demo with a fake email address, the content of the email will be stored in './authelia/notification.txt'.
Upon registering, you can grab this link easily by running the following command: 'grep -Eo '"https://.*" ' ./authelia/notification.txt'.
EOF

4
compose/local/traefik/certificates.yml 100644
View File

@ -0,0 +1,4 @@
tls:
certificates:
- certFile: /etc/traefik/certs/cert.pem
keyFile: /etc/traefik/certs/key.pem

14
compose/local/users_database.yml 100644
View File

@ -0,0 +1,14 @@
###############################################################
# Users Database #
###############################################################
# This file can be used if you do not have an LDAP set up.
# List of users
users:
<USERNAME>:
password: "<PASSWORD>"
email: <USERNAME>@example.com
groups:
- admins
- dev

2
docs/configuration/storage/mysql.md
View File

@ -3,7 +3,7 @@ layout: default
title: MySQL
parent: Storage backends
grand_parent: Configuration
nav_order: 3
nav_order: 2
---
# MySQL

2
docs/configuration/storage/postgres.md
View File

@ -3,7 +3,7 @@ layout: default
title: PostgreSQL
parent: Storage backends
grand_parent: Configuration
nav_order: 2
nav_order: 3
---
# PostgreSQL

47
docs/contributing/index.md
View File

@ -6,3 +6,50 @@ has_children: true
---
# Contributing
## Development workflow
**Authelia** and its development workflow can be tested with Docker and docker-compose on Linux.
In order to deploy the current version of Authelia locally, run the following command and
follow the instructions of bootstrap.sh:
$ source bootstrap.sh
Then, start the *Standalone* [suite].
$ authelia-scripts suites setup Standalone
A [suite] is kind of a virtual environment for running Authelia in a complete ecosystem.
If you want more details please read the related [documentation](./contributing/suites.md).
## FAQ
### What version of Docker and docker-compose should I use?
Here are the versions used for testing in Buildkite:
$ docker --version
Docker version 19.03.5, build 633a0ea838
$ docker-compose --version
docker-compose version 1.24.1, build unknown
### How can I serve my application under example.com?
Don't worry, you don't need to own the domain *example.com* to test Authelia.
Copy the following lines in your /etc/hosts.
192.168.240.100 home.example.com
192.168.240.100 login.example.com
192.168.240.100 singlefactor.example.com
192.168.240.100 public.example.com
192.168.240.100 secure.example.com
192.168.240.100 mail.example.com
192.168.240.100 mx1.mail.example.com
`192.168.240.100` is the IP attributed by Docker to the reverse proxy. Once done
you can access the listed sub-domains from your browser and they will target
the reverse proxy.
[suite]: ./contributing/suites.md

3
docs/deployment/deployment-ha.md
View File

@ -27,9 +27,6 @@ persist user configurations and one or more nginx reverse proxies configured to
be used with Authelia. With such a setup **Authelia** can easily be scaled to
multiple instances to evenly handle the traffic.
**NOTE**: If you don't have all those components, don't worry, there is a way to
deploy **Authelia** with only nginx. This is described in [Deployment - Lite](./deployment-lite.md).
Here are the available steps to deploy **Authelia** given
the configuration file is **/path/to/your/configuration.yml**. Note that you can
create your own configuration file from [config.template.yml] located at

83
docs/deployment/deployment-lite.md
View File

@ -6,55 +6,40 @@ parent: Deployment
# Lite Deployment
**Authelia** can be deployed as a lite setup not requiring any SQL server,
Redis cluster or LDAP server. In some cases, like protecting personal projects/websites,
it can be fine to use that setup but beware that this setup is non-resilient to failures
so it should be used at your own risk.
**Authelia** can be deployed as a lite setup with minimal external dependencies.
The setup is called lite because it reduces the number of components in the architecture
to a reverse proxy such as Nginx, Traefik or HAProxy, Authelia and Redis.
The setup is called lite since it reduces the number of components in the architecture to
only two: a reverse proxy such as Nginx, Traefik or HAProxy and Authelia.
This setup assumes you have basic knowledge and understanding of IP addresses, DNS and port
forwarding. You should setup the domain you intend to protect with Authelia to point to your
external IP address and port forward ports `80` and `443` to the host you plan to host the
`docker-compose.yml` bundle.
Port 80 is utilised by LetsEncrypt for certificate challenges, this will [automatically
provision](https://docs.traefik.io/https/acme/) up-to-date certificates for your domain(s).
Traefik publishes the respective services with LetsEncrypt provided certificates on port `443`.
The provided examples protect the Traefik dashboard with Authelia's one-factor auth
(traefik.example.com) and two instances of the
[whoami container](https://hub.docker.com/r/containous/whoami) with Authelia being
bypassed (public.example.com) and another with it's two-factor auth (secure.example.com).
If you happen to already have an external SQL instance (MariaDB, MySQL or Postgres) this
setup can easily be adapted to utilise said [service](../configuration/storage/index.md).
## Steps
- `git clone https://github.com/authelia/authelia.git`
- `cd authelia/compose/lite`
- Modify the `users_database.yml` the default username and password is `authelia`
- Modify the `configuration.yml` and `docker-compose.yml` with your respective domains and secrets
- `docker-compose up -d`
## Reverse Proxy
Documentation for deploying a reverse proxy collaborating with Authelia is available
[here](./supported-proxies/index.md).
Please note that Authelia only works for websites served over HTTPS because the session cookie
can only be transmitted over secure connections. Therefore, if you need to generate a
self-signed certificate for your setup, you can use the dedicated helper function provided
by the authelia binary.
# Generate a certificate covering "example.com" for one year in the /tmp/certs/ directory.
$ docker run authelia/authelia authelia certificates generate --host example.com --dir /tmp/certs/
You can see all available options with the following command:
$ docker run authelia/authelia authelia certificates generate --help
## Discard components
### Discard SQL server
It's possible to use a SQLite file instead of a SQL server as documented
[here](../configuration/storage/sqlite.md).
### Discard Redis
Connection details to Redis are optional. If not provided, sessions will
be stored in memory instead. This has the inconvenient of logging out users
every time Authelia restarts.
The documentation about session management is available
[here](../configuration/session.md).
### Discard LDAP
**Authelia** can use a file backend in order to store users instead of a
LDAP server or an Active Directory.
To use a file backend instead of a LDAP server, please follow the related
documentation [here](../configuration/authentication/file.md).
The [Lite bundle](https://github.com/authelia/authelia/blob/master/compose/lite/docker-compose.yml)
provides pre-made examples with [Traefik2.x](./supported-proxies/traefik2.x.md), you can swap this
out for any of the [supported proxies](./supported-proxies/index.md).
## FAQ
@ -64,10 +49,4 @@ This documentation gives instructions that will make **Authelia** non
resilient to failures and non scalable by preventing you from running multiple
instances of the application. This means that **Authelia** won't be able to distribute
the load across multiple servers and it will prevent failover in case of a
crash or an hardware issue. Moreover, users will be logged out every time
Authelia restarts.
### Why aren't all those steps automated?
We would really be more than happy to review any contribution with an Ansible playbook,
a Chef cookbook or whatever else to automate the process.
crash or an hardware issue.

2
docs/deployment/supported-proxies/traefik1.x.md
View File

@ -36,7 +36,7 @@ services:
image: traefik:v1.7.20-alpine
container_name: traefik
volumes:
- '/var/run/docker.sock:/var/run/docker.sock'
- /var/run/docker.sock:/var/run/docker.sock
networks:
- net
labels:

9
docs/deployment/supported-proxies/traefik2.x.md
View File

@ -40,6 +40,7 @@ services:
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.api.rule=Host(`traefik.example.com`)'
- 'traefik.http.routers.api.entrypoints=https'
- 'traefik.http.routers.api.service=api@internal'
@ -50,6 +51,7 @@ services:
command:
- '--api'
- '--providers.docker=true'
- '--providers.docker.exposedByDefault=false'
- '--entrypoints.http=true'
- '--entrypoints.http.address=:80'
- '--entrypoints.https=true'
@ -67,9 +69,12 @@ services:
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.authelia.rule=Host(`login.example.com`)'
- 'traefik.http.routers.authelia.entrypoints=https'
- 'traefik.http.routers.authelia.tls=true'
- 'traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/verify?rd=https://login.example.com/'
- 'traefik.http.middlewares.authelia.forwardauth.trustForwardHeader=true'
expose:
- 9091
restart: unless-stopped
@ -85,11 +90,11 @@ services:
networks:
- net
labels:
- 'traefik.enable=true'
- 'traefik.http.routers.nextcloud.rule=Host(`nextcloud.example.com`)'
- 'traefik.http.routers.nextcloud.entrypoints=https'
- 'traefik.http.routers.nextcloud.tls=true'
- 'traefik.http.routers.nextcloud.middlewares=authelia'
- 'traefik.http.middlewares.authelia.forwardAuth.address=http://authelia:9091/api/verify?rd=https://login.example.com/'
- 'traefik.http.routers.nextcloud.middlewares=authelia@docker'
expose:
- 443
restart: unless-stopped

93
docs/getting-started.md
View File

@ -6,84 +6,29 @@ nav_order: 2
# Getting Started
**Authelia** can be tested in a matter of seconds with Docker and docker-compose.
## Docker Compose
In order to deploy the current version of Authelia locally, run the following
command and follow the instructions of bootstrap.sh:
### Steps
$ source bootstrap.sh
These commands are intended to be run sequentially:
Then, start the *Standalone* [suite].
- `git clone https://github.com/authelia/authelia.git`
- `cd authelia/compose/local`
- `sudo ./setup.sh` *sudo is required to modify the `/etc/hosts` file*
$ authelia-scripts suites setup Standalone
You can now visit the following locations; replace example.com with the domain you specified in the setup script:
- https://public.example.com - Bypasses Authelia
- https://traefik.example.com - Secured with Authelia one-factor authentication
- https://secure.example.com - Secured with Authelia two-factor authentication (see note below)
A [suite] is kind of a virtual environment for running Authelia in a complete ecosystem.
If you want more details please read the related [documentation](./contributing/suites.md).
You will need to authorize the self-signed certificate upon visiting each domain.
To visit https://secure.example.com you will need to register a device for second factor authentication and confirm by clicking on a link sent by email.
Since this is a demo with a fake email address, the content of the email will be stored in './authelia/notification.txt'.
Upon registering, you can grab this link easily by running the following command: `grep -Eo '"https://.*" ' ./authelia/notification.txt`.
## Test it!
## Deployment
After few seconds the services should be running and you should be able to
visit [https://home.example.com:8080/](https://home.example.com:8080/).
When accessing the login page, since this is a test environment a
self-signed certificate exception should appear, it has to be trusted
before you can get to the home page.
The certificate must also be trusted for each subdomain, therefore it is
normal to see this exception several times.
Below is what the login page looks like after you accepted all exceptions:
<p align="center">
<img src="./images/1FA.png" width="400">
</p>
You can use one of the users listed in
[https://home.example.com:8080/](https://home.example.com:8080/).
The rights granted to each user and group is also provided in the page as
a list of rules.
At some point, you'll be required to register your second factor device.
Since your security is **Authelia**'s priority, it will send
an email to the email address of the user to confirm the user identity.
Since you are running a test environment, a fake webmail called
*MailCatcher* has been deployed for you to check out the email and
confirm your identity.
The webmail is accessible at
[http://mail.example.com:8080](http://mail.example.com:8080).
Enjoy!
## FAQ
### What version of Docker and docker-compose should I use?
Here are the versions used for testing in Buildkite:
$ docker --version
Docker version 19.03.5, build 633a0ea838
$ docker-compose --version
docker-compose version 1.24.1, build unknown
### How can I serve my application under example.com?
Don't worry, you don't need to own the domain *example.com* to test Authelia.
Copy the following lines in your /etc/hosts.
192.168.240.100 home.example.com
192.168.240.100 login.example.com
192.168.240.100 singlefactor.example.com
192.168.240.100 public.example.com
192.168.240.100 secure.example.com
192.168.240.100 mail.example.com
192.168.240.100 mx1.mail.example.com
`192.168.240.100` is the IP attributed by Docker to the reverse proxy. Once done
you can access the listed sub-domains from your browser and they will target
the reverse proxy.
### What should I do if I want to contribute?
You can refer to the dedicated documentation [here](./contributing/index.md).
[suite]: ./contributing/suites.md
So you're convinced that Authelia is what you need. You can head to the deployment documentation [here](./deployment/index.md).
Some recipes have been crafted for helping with the bootstrap of your environment.
You can choose between a [lite](./deployment/deployment-lite.md) deployment which is deployment advised for a single server setup.
However, this setup just does not scale. If you want a full environment that can scale out, use the [HA](./deployment/deployment-ha.md) or [Kubernetes](./deployment/deployment-kubernetes.md) deployment documentation.