Docker

Testing / Local Evaluation

For getting a first look at Rauthy, you can start it with docker (or any other container runtime) on your localhost. The image contains a basic default config which is sufficient for local testing ( don't use it in production, it contains hardcoded secrets).

docker run -it --rm -e LOCAL_TEST=true -p 8443:8443 ghcr.io/sebadob/rauthy:0.35.1

To proceed, go to First Start, or do the production setup below to have persistence.

Testing / Evaluation with E-Mail

You can do anything you like with the default admin@localhost account. Rauthy does not have any special accounts. It is an account like any other. The only reason it is a Rauthy admin, is because it is assigned to the rauthy_admin role.

If you like to test creating new accounts or password reset flows though, you need to have at least a minimal setup that is able to send E-Mails. The easiest way (works on localhost only) is the below docker-compose.yaml:

services:

  mailcrab:
    image: marlonb/mailcrab:latest
    ports:
      - "1080:1080"

  rauthy:
    image: ghcr.io/sebadob/rauthy:0.35.1
    environment:
      - LOCAL_TEST=true
      - SMTP_URL=mailcrab
      - SMTP_PORT=1025
      - SMTP_DANGER_INSECURE=true
    volumes:
      - data:/app/data
    ports:
      - "8443:8443"
    depends_on:
      - mailcrab

volumes:
  data:

Save this into docker-compose.yaml and start with:

docker compose up -d

You then need the logs output from Rauthy to read the random password for the admin@localhost account:

docker compose logs -f rauthy

Any outgoing E-Mail will be caught by mailcrab, which can be accessed via http://localhost:1080 . When you are done testing, shut down with

docker compose down

Production Setup

For going to production or to test more in-depth, you need to create a config that matches your environment.

The first thing you want to do is to add a volume mount for the database. The second thing is to provide a more appropriate config.

Rauthy expects at least the very basics in a config file. Most other values could be set via ENV vars. It parses both, the config first and any env var that is set will overwrite a possibly existing one from the config. You can add environment variables to the startup command with the -e option.

1. We want to create a new directory for Rauthy's persistent data

mkdir -p rauthy/data rauthy/tls

2. Add the new config file.

Rauthy (since v0.35) comes with a CLI. You can use it to generate a (basic) config file to get you started. We will use it from inside the container. However, since it's rootless and runs with user 10001:10001 inside, we need to modify access rights.

sudo chown -R 10001:$(id -g) rauthy

Next, we set an alias to be able to work with the CLI comfortably.

alias rauthy='docker run -it --rm -v $(pwd)/rauthy/data:/app/data -p 8080:8080 ghcr.io/sebadob/rauthy'

Make sure it's working:

rauthy --help

We can then use it to generate a config:

rauthy generate-config -o data/config-generated.toml

Once finished, you will have a new config file at rauthy/data/config-generated.toml. You can only access it as root though, because as mentioned above, the binary inside the container runs as 10001:10001.

sudo cat rauthy/data/config-generated.toml

You can either use it directly, or you can evaluate it first. The final config will be expected in rauthy/config.toml by default. However, let's start with the generated one and make sure everything works as expected:

rauthy serve -c data/config-generated.toml

When everything is working as expected, move the generated config in the final location:

sudo mv rauthy/data/config-generated.toml rauthy/config.toml

3. Access rights for the Database files

Finalize / harden access rights:

sudo chmod 0600 rauthy/config.toml && \
sudo chmod 0700 rauthy/data && \
sudo chmod 0700 rauthy/tls && \
sudo chown -R 10001:10001 rauthy

4. Adopt the config to your liking.

The config-generator only gets you started and asks for the very basic requirements. There is a lot more you can configure. Take a look at the reference config and adopt everything to your needs.

For an in-depth guide on a production ready config, check the Production Config section.

5. Start the container with volume mounts

docker run -d \
    -v $(pwd)/rauthy/config.toml:/app/config.toml \
    -v $(pwd)/rauthy/data:/app/data \
    -p 8443:8443 \
    --name rauthy \
    ghcr.io/sebadob/rauthy:0.35.1

• -v $(pwd)/rauthy/config.toml:/app/config.toml mounts the config in the correct place
• -v $(pwd)/rauthy/data:/app/data mounts the volume for Hiqlite
• -p 8443:8443 needs to match your configured server.port_http or server.port_https of course. If you use a reverse proxy inside a docker network, you don't need to expose any port, but you need to make sure to set server.scheme = "http", server.proxy_mode = true and the correct value for server.trusted_proxies.-

6. You can now proceed with the First Start steps.