Merge pull request #302 from clems4ever/improve-doc
Add details on how to deploy Authelia in a dev environment.pull/293/head
Clément Michaud
GitHub
commit
76326d5ff7
23
README.md
23
README.md
|
|
@ -41,7 +41,14 @@ For more details about the features, follow [Features](./docs/features.md).
|
|||
|
||||
## Getting Started
|
||||
|
||||
Follow [Getting Started](./docs/getting-started.md).
|
||||
If you want to quickly test Authelia with Docker, we recommend you read
|
||||
[Getting Started](./docs/getting-started.md).
|
||||
|
||||
## Deployment
|
||||
|
||||
Now that you have tested **Authelia** and you want to try it out in your own infrastructure, you can learn how to deploy and use it with
|
||||
[Deployment](./docs/deployment-production.md). This guide will show you how to deploy
|
||||
it on bare metal as well as on Kubernetes.
|
||||
|
||||
## Security
|
||||
|
||||
|
|
@ -49,15 +56,6 @@ If you want more information about the security measures applied by
|
|||
**Authelia** and some tips on how to set up **Authelia** in a secure way,
|
||||
refer to [Security](./docs/security.md).
|
||||
|
||||
## Deployment
|
||||
|
||||
To learn how to deploy **Authelia** or use it on Kubernetes, please follow
|
||||
[Deployment](./docs/deployment.md).
|
||||
|
||||
## Build Authelia
|
||||
|
||||
Follow [Build](./docs/build.md).
|
||||
|
||||
## Changelog
|
||||
|
||||
See [CHANGELOG.md](CHANGELOG.md).
|
||||
|
|
@ -71,6 +69,11 @@ or review pull requests and take part to discussions in
|
|||
|
||||
We are already greatful to contributors listed in
|
||||
[CONTRIBUTORS.md](CONTRIBUTORS.md) for their contributions to the project.
|
||||
Be the next in the list!
|
||||
|
||||
## Build Authelia
|
||||
|
||||
If you want to contribute with code, you should follow the documentation explaining how to [build](./docs/build.md) the application.
|
||||
|
||||
## Donation
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Build
|
||||
|
||||
**Authelia** is written in Typescript and built with Grunt.
|
||||
**Authelia** is written in Typescript and built with [Grunt](https://gruntjs.com/).
|
||||
|
||||
In order to build **Authelia**, you need to make sure Node v8 and NPM is
|
||||
installed on your machine.
|
||||
|
|
@ -22,14 +22,14 @@ And, this command to build **Authelia** under dist/:
|
|||
The client is written in Typescript and uses jQuery. It is built as part of
|
||||
the global `build` Grunt command.
|
||||
|
||||
The server is written in Typescript. It is built as part of the global `build`
|
||||
The server is written in Typescript. It is also built as part of the global `build`
|
||||
Grunt command.
|
||||
|
||||
### Tests
|
||||
|
||||
Grunt also handles the commands to run the tests. There are several type of
|
||||
tests for **Authelia**: unit tests for the server, unit tests for the client
|
||||
and integration tests for both.
|
||||
tests for **Authelia**: unit tests for the server, the client and a shared
|
||||
library and an integration test suite testing both components together.
|
||||
|
||||
The unit tests are written with Mocha while integration tests are using
|
||||
Cucumber and Mocha.
|
||||
|
|
@ -44,12 +44,16 @@ To run the server unit tests, run:
|
|||
|
||||
./node_modules/.bin/grunt test-server
|
||||
|
||||
To run the shared library unit tests, run:
|
||||
|
||||
./node_modules/.bin/grunt test-shared
|
||||
|
||||
### Integration tests
|
||||
|
||||
Integration tests are mainly based on Selenium so they
|
||||
need a complete environment to be set up.
|
||||
need a complete environment to be run.
|
||||
|
||||
Start by making sure **Authelia** is built with:
|
||||
You can start by making sure **Authelia** is built with:
|
||||
|
||||
grunt build
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Configuration
|
||||
|
||||
Authelia is highly configurable thanks to a configuration file.
|
||||
There is a documented template configuration, called [config.template.yml], at
|
||||
There is a documented template configuration, called [config.template.yml](./config.template.yml), at
|
||||
the root of the repository. All the details are documented there.
|
||||
|
||||
When running **Authelia**, you can specify your configuration file by passing
|
||||
|
|
|
|||
|
|
@ -0,0 +1,149 @@
|
|||
# Deployment for Dev
|
||||
|
||||
1. [Deploy With npm](#deploy-with-npm)
|
||||
2. [Deploy With Docker](#deploy-with-docker)
|
||||
3. [Deploy nginx](#deploy-nginx)
|
||||
4. [Discard components](#discard-components)
|
||||
1. [Discard MongoDB](#discard-mongodb)
|
||||
2. [Discard Redis](#discard-redis)
|
||||
3. [Discard LDAP](#discard-ldap)
|
||||
5. [FAQ](#faq)
|
||||
|
||||
**WARNING:** *the instructions given in this documentation are not meant
|
||||
to be used for production environments since it will make **Authelia**
|
||||
non resilient to failures.*
|
||||
|
||||
**NOTE:** If not done already, we highly recommend you first follow the
|
||||
[Getting Started] documentation.
|
||||
|
||||
In some cases, like protecting personal websites, it can be fine to use
|
||||
**Authelia** in a non highly-available manner. Fortunately, we can
|
||||
achieve to run it along with one reverse proxy meaning the setup is
|
||||
then reduced to only two components: Authelia and nginx.
|
||||
|
||||
As for a regular deployment in production, you need to install **Authelia**
|
||||
either by pulling the Docker image or installing the npm package and run
|
||||
it with a configuration file passed as argument.
|
||||
|
||||
## Deploy with npm
|
||||
|
||||
npm install -g authelia
|
||||
authelia /path/to/your/config.yml
|
||||
|
||||
## Deploy with Docker
|
||||
|
||||
docker pull clems4ever/authelia
|
||||
docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
|
||||
|
||||
## Deploy Nginx
|
||||
|
||||
You also need to install nginx and take [example/nginx/minimal/nginx.conf](./example/nginx/minimal/nginx.conf) as an example of configuration.
|
||||
|
||||
## Discard components
|
||||
|
||||
### Discard MongoDB
|
||||
|
||||
There is an option in the configuration file to discard MongoDB and use
|
||||
your local filesystem to store the database data. This option will therefore
|
||||
prevent you from running multiple instances of **Authelia** in parallel.
|
||||
Consequently, this option is not meant to be used in production.
|
||||
|
||||
Here is the configuration block you should use:
|
||||
|
||||
storage:
|
||||
# The directory where the DB files will be saved
|
||||
local:
|
||||
path: /var/lib/authelia/store
|
||||
|
||||
### Discard Redis
|
||||
|
||||
There is an option in the configuration file to discard Redis and use the
|
||||
memory of the server to store the KV data. This option will therefore
|
||||
prevent you from running multiple instances of **Authelia** in parallel and
|
||||
will make you lose user sessions if the application restarts. This
|
||||
concretely means that all your users will need to authenticate again in
|
||||
that case. Hence, this option is not meant to be used in production.
|
||||
|
||||
To use memory instead of a Redis backend, just comment out the Redis
|
||||
connection details in the following block:
|
||||
|
||||
session:
|
||||
...
|
||||
# # The redis connection details
|
||||
# redis:
|
||||
# host: redis
|
||||
# port: 6379
|
||||
# password: authelia
|
||||
|
||||
### Discard LDAP
|
||||
|
||||
**Authelia** can use a file backend in order to store users instead of a
|
||||
LDAP server or an Active Directory. This mode will therefore prevent you
|
||||
from running multiple instances of **Authelia** in parallel and is therefore
|
||||
discouraged for production environments.
|
||||
|
||||
To use a file backend instead of a LDAP server, you should first duplicate
|
||||
the file [users_database.yml](../users_database.yml) and edit it to add the
|
||||
users you want.
|
||||
|
||||
The content of this file is as follows:
|
||||
|
||||
users:
|
||||
...
|
||||
john:
|
||||
password: "{CRYPT}$6$rounds=500000$jgiCMRyGXzoqpxS3$w2pJeZnnH8bwW3zzvoMWtTRfQYsHbWbD/hquuQ5vUeIyl9gdwBIt6RWk2S6afBA0DPakbeWgD/4SZPiS0hYtU/"
|
||||
email: john.doe@authelia.com
|
||||
groups:
|
||||
- admins
|
||||
- dev
|
||||
|
||||
The password is hashed and salted as it is in LDAP servers with salted SHA-512. Here is a one-liner to generate such hashed password:
|
||||
|
||||
python3 -c 'import crypt; print("{CRYPT}" + crypt.crypt("mypassword", crypt.mksalt(crypt.METHOD_SHA512, rounds=500000)))'
|
||||
|
||||
Once the file is created, edit the configuration file with the following
|
||||
block (as used in [config.minimal.yml](../config.minimal.yml)):
|
||||
|
||||
authentication_backend:
|
||||
file:
|
||||
path: /etc/authelia/users_database.yml
|
||||
|
||||
instead of (used in [config.template.yml](../config.template.yml)):
|
||||
|
||||
authentication_backend:
|
||||
ldap:
|
||||
url: ldap://openldap
|
||||
base_dn: dc=example,dc=com
|
||||
|
||||
additional_users_dn: ou=users
|
||||
users_filter: cn={0}
|
||||
|
||||
additional_groups_dn: ou=groups
|
||||
groups_filter: (&(member={dn})(objectclass=groupOfNames))
|
||||
|
||||
group_name_attribute: cn
|
||||
|
||||
mail_attribute: mail
|
||||
|
||||
user: cn=admin,dc=example,dc=com
|
||||
password: password
|
||||
|
||||
## FAQ
|
||||
|
||||
### Can you give more details on why this is not suitable for production environments?
|
||||
|
||||
This documentation gives instructions that will make **Authelia** non
|
||||
highly-available 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 accross multiple servers and it will prevent failover in case of a
|
||||
crash or an hardware issue. Moreover, it will also prevent from reliably
|
||||
persisting data and consequently fail access to your platform as the devices
|
||||
registered by your users will be lost.
|
||||
|
||||
### Why is this not automated?
|
||||
|
||||
Well, as stated before those instructions are not meant to be applied for
|
||||
a production environment. That being said, in some cases it is just fine and
|
||||
so writing an Ansible playbook to automate all this process would be great.
|
||||
We would really be more than happy to review such a PR.
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
# Deployment for Production
|
||||
|
||||
**Authelia** can be deployed on bare metal or on Kubernetes with two
|
||||
different kind of artifacts: an npm package or a Docker image.
|
||||
|
||||
**NOTE:** If not done already, we highly recommend you first follow the
|
||||
[Getting Started] documentation.
|
||||
|
||||
## On Bare Metal
|
||||
|
||||
**Authelia** has been designed to be a proxy companion handling the
|
||||
authentication and authorization requests for your entire infrastructure.
|
||||
|
||||
As **Authelia** will be key in your architecture, it requires several
|
||||
components to make it highly-available. Deploying it in production means having an LDAP server for storing the information about the users, a Redis cache to store the user sessions in a distributed manner, a
|
||||
MongoDB to 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 for Devs].
|
||||
|
||||
Here are the available steps to deploy **Authelia** given
|
||||
the configuration file is **/path/to/your/config.yml**. Note that you can
|
||||
create your own configuration file from [config.template.yml] located at
|
||||
the root of the repo.
|
||||
|
||||
### Deploy With NPM
|
||||
|
||||
npm install -g authelia
|
||||
authelia /path/to/your/config.yml
|
||||
|
||||
### Deploy With Docker
|
||||
|
||||
docker pull clems4ever/authelia
|
||||
docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
|
||||
|
||||
## On top of Kubernetes
|
||||
|
||||
<img src="/images/kube-logo.png" width="24" align="left">
|
||||
|
||||
**Authelia** can also be used on top of [Kubernetes] using [nginx ingress
|
||||
controller](https://github.com/kubernetes/ingress-nginx).
|
||||
|
||||
Please refer to the following [documentation](../example/kube/README.md)
|
||||
for more information.
|
||||
|
||||
[config.template.yml]: ../config.template.yml
|
||||
[Getting Started]: ./getting-started.md
|
||||
[Deployment for Devs]: ./deployment-dev.md
|
||||
[Kubernetes]: https://kubernetes.io/
|
||||
|
||||
## FAQ
|
||||
|
||||
### Why is this not automated?
|
||||
|
||||
Ansible would be a very good candidate to automate the installation of such
|
||||
an infrastructure on bare metal. We would be more than happy to review any PR on that matter.
|
||||
|
||||
Regarding Kubernetes, the right way to go would be to write a helm recipe.
|
||||
Again, we would be glad to review any PR implementing this.
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
# Deployment
|
||||
|
||||
**Authelia** can be deployed in two different ways: npm and docker.
|
||||
|
||||
Here are the available steps to deploy **Authelia** on your machine given
|
||||
your configuration file is **/path/to/your/config.yml**. Note that you can
|
||||
create your own the configuration file from [config.template.yml] at the root
|
||||
of the repo.
|
||||
|
||||
## Standalone
|
||||
|
||||
**Authelia** has been designed to be a proxy companion handling the SSO.
|
||||
Therefore, deploying it in production means having an LDAP, a Redis, a
|
||||
MongoDB and one or more nginx running and configured to be used with
|
||||
Authelia.
|
||||
|
||||
If you don't have all of this, don't worry, there is a way to deploy
|
||||
**Authelia** with only an nginx. To do so, please refer to the
|
||||
[Getting Started]. Otherwise here are the command to run Authelia in your
|
||||
environment.
|
||||
|
||||
### With NPM
|
||||
|
||||
npm install -g authelia
|
||||
authelia /path/to/your/config.yml
|
||||
|
||||
### With Docker
|
||||
|
||||
docker pull clems4ever/authelia
|
||||
docker run -v /path/to/your/config.yml:/etc/authelia/config.yml clems4ever/authelia
|
||||
|
||||
## Kubernetes
|
||||
|
||||
<img src="/images/kube-logo.png" width="24" align="left">
|
||||
|
||||
**Authelia** can also be used on top of Kubernetes using the nginx ingress
|
||||
controller.
|
||||
|
||||
Please refer to the following [README](../example/kube/README.md) for more
|
||||
information.
|
||||
|
||||
[config.template.yml]: ../config.template.yml
|
||||
[Getting Started]: ./getting-started.md
|
||||
|
|
@ -11,7 +11,7 @@ You can find an example of the configuration of the LDAP backend in
|
|||
[config.template.yml].
|
||||
|
||||
<p align="center">
|
||||
<img src="../images/second_factor.png" width="400">
|
||||
<img src="../images/first_factor.png" width="400">
|
||||
</p>
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,14 @@
|
|||
# Getting Started
|
||||
|
||||
**Authelia** can be tested in a matter of seconds with docker-compose based
|
||||
on the latest image available on [Dockerhub] or by building the latest version
|
||||
from the sources and use it in docker-compose.
|
||||
on the latest image available on [Dockerhub].
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
In order to test **Authelia**, we need to make sure that:
|
||||
- **Docker** and **docker-compose** are installed.
|
||||
- Some ports are open for listening on your machine.
|
||||
- Some subdomains redirect to your machine to simulate the fact that some
|
||||
applications you want to protect are served by some subdomains of
|
||||
**example.com** on your machine.
|
||||
- **Docker** and **docker-compose** are installed on your computer.
|
||||
- Ports 8080 and 8085 are not already used on your machine.
|
||||
- Some subdomains of **example.com** redirect to your test infrastructure.
|
||||
|
||||
### Docker & docker-compose
|
||||
|
||||
|
|
@ -19,30 +16,27 @@ Make sure you have **docker** and **docker-compose** installed on your
|
|||
machine.
|
||||
Here are the versions used for testing in Travis:
|
||||
|
||||
docker --version
|
||||
$ docker --version
|
||||
Docker version 17.03.1-ce, build c6d412e
|
||||
|
||||
gave *Docker version 17.03.1-ce, build c6d412e*.
|
||||
|
||||
docker-compose --version
|
||||
|
||||
gave *docker-compose version 1.14.0, build c7bdf9e*.
|
||||
$ docker-compose --version
|
||||
docker-compose version 1.14.0, build c7bdf9e
|
||||
|
||||
### Available port
|
||||
|
||||
Make sure you don't have anything listening on port 8080 and 8085.
|
||||
|
||||
The port 8080 will be used by nginx to serve **Authelia** and the applications
|
||||
we want to protect with **Authelia**.
|
||||
The port 8080 will be our frontend load balancer serving both **Authelia**'s portal and the applications we want to protect.
|
||||
|
||||
The port 8085 is serving a webmail used to receive emails sent by **Authelia**
|
||||
The port 8085 is serving a webmail used to receive fake emails sent by **Authelia**
|
||||
to validate your identity when registering U2F or TOTP secrets or when
|
||||
resetting your password.
|
||||
|
||||
### Subdomain aliases
|
||||
|
||||
Make sure the following subdomains redirect to your machine by adding the
|
||||
following lines to your **/etc/hosts**. It will alias the subdomains so that
|
||||
nginx can redirect requests to the correct virtual host.
|
||||
In order to simulate the behavior of a DNS resolving some test subdomains of **example.com** to your machine, we
|
||||
need to add the following lines to your **/etc/hosts**. It will alias the
|
||||
subdomains so that nginx can redirect requests to the correct virtual host.
|
||||
|
||||
127.0.0.1 home.example.com
|
||||
127.0.0.1 public.example.com
|
||||
|
|
@ -53,40 +47,41 @@ nginx can redirect requests to the correct virtual host.
|
|||
127.0.0.1 single_factor.example.com
|
||||
127.0.0.1 login.example.com
|
||||
|
||||
## From Dockerhub
|
||||
## Deploy
|
||||
|
||||
To deploy **Authelia** using the latest image from [Dockerhub], run the
|
||||
following command:
|
||||
|
||||
./scripts/example-dockerhub/deploy-example.sh
|
||||
|
||||
## From source
|
||||
|
||||
To deploy **Authelia** from source, follow the [build] manual and run the
|
||||
following commands:
|
||||
|
||||
./scripts/example-commit/deploy-example.sh
|
||||
|
||||
## Test it!
|
||||
|
||||
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, a self-signed certificate exception should
|
||||
appear, it has to be trusted before you can get to the home page.
|
||||
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:
|
||||
Below is what the login page looks like after you accepted all exceptions:
|
||||
|
||||
<p align="center">
|
||||
<img src="../images/first_factor.png" width="400">
|
||||
</p>
|
||||
|
||||
At some point, you'll be required to register a secret for setting up
|
||||
the second factor. **Authelia** will send an email to the user email
|
||||
address to confirm the user identity. In order to receive it, visit the
|
||||
webmail at [http://localhost:8085](http://localhost:8085).
|
||||
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 there.
|
||||
|
||||
At some point, you'll be required to register your second factor, either
|
||||
U2F or TOTP. 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 we're running a test environment, we provide a fake webmail called
|
||||
*MailCatcher* from which you can checkout the email and confirm
|
||||
your identity.
|
||||
The webmail is accessible from
|
||||
[http://localhost:8085](http://localhost:8085).
|
||||
|
||||
**Note:** If you cannot deploy the fake webmail for any reason. You can
|
||||
configure **Authelia** to use the filesystem notifier (option available
|
||||
|
|
|
|||
Loading…
Reference in New Issue