Skip to main content

Setup with a reverse proxy and custom domain

info

This guide was updated for the latest version of Grimoire (>0.4).

Hey there! In this guide we will cover the setup of Grimoire with a simple reverse proxy. We will use Traefik as an example, but you can use any other reverse proxy of your choice.

What we want to achieve is to have Grimoire running behind the reverse proxy, so that we can access them using the same domain name, but different paths.

Thanks to that, we can have the following URLs https://grimoire.[your-domain.com]

warning

Disclaimer: This guide is not meant to be used in production. It's just a simple example of how you can run Grimoire and PocketBase behind a reverse proxy. If you want to use it in production, please make sure to secure your installation properly.

Prerequisites​

All prerequisites are meant for the machine that will be running the reverse proxy.

Steps​

Step 1: Create the compose file​

For the sake of simplicity, we will clone the repository to the same machine that will be running the reverse proxy. If you really want to get as few files as possible, you can just copy the docker-compose.yml file.

services:
  grimoire:
    image: goniszewski/grimoire:latest
    container_name: grimoire
    restart: unless-stopped
    environment:
      - PORT=5173
      - PUBLIC_HTTPS_ONLY=false
      - PUBLIC_ORIGIN=https://grimoire.[your-domain.com]
      - PUBLIC_SIGNUP_DISABLED=false
    volumes:
      - grimoire_data:/app/data/
    build:
      context: .
      dockerfile: Dockerfile
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:$PORT/api/health || exit 1
      interval: 30s
      timeout: 10s
      retries: 3
    ports:
      - '${PORT:-5173}:${PORT:-5173}'
volumes:
  grimoire_data:

Step 2: Update the docker-compose.yml file to add reverse proxy magic​

Now let's focus on the environment section of the grimoire service. We need to review the existing settings and update them accordingly.

  • PORT: This sets the internal port on which Grimoire will run. Default is 5173.
  • PUBLIC_HTTPS_ONLY: This determines whether Grimoire should enforce HTTPS connections.
    • Set to true if you're using HTTPS (recommended for production).
    • Set to false if you're using HTTP (e.g., for local development).
    • When set to true, Grimoire will redirect all HTTP traffic to HTTPS and set the Secure flag on cookies.
  • PUBLIC_ORIGIN: Set this to the full URL where Grimoire will be accessible, including the protocol (http:// or https://).
    • Example: https://grimoire.yourdomain.com
    • This is crucial for proper functioning of authentication and API requests.
  • PUBLIC_SIGNUP_DISABLED: Controls whether new user registrations are allowed.
    • Set to true to disable public sign-ups (recommended for private instances).
    • Set to false to allow anyone to create an account.

Remember to adjust these values according to your specific setup and security requirements.

note

If you want to use an already existing Traefik installation, you can skip the next part of this step.

Under services: add the following:

docker-compose.yml
  reverse-proxy:
    image: traefik:v2.10
    container_name: reverse-proxy
    command:
      - --api.insecure=true
      - --providers.docker
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - grimoire

Step 3: Tell Grimoire about the proxy​

Add these labels to your grimoire service:

docker-compose.yml
    labels:
      - traefik.http.routers.grimoire.rule=Host(`grimoire.[your-domain.com]`)
    # network_mode: bridge # uncomment this line if you're using external Traefik installation

Step 4: Let's review the docker-compose.yml file content​

Depending on your setup, your docker-compose.yml file should look similar to this:

docker-compose.yml
services:
  reverse-proxy:
    image: traefik:v2.10
    container_name: reverse-proxy
    command:
      - --api.insecure=true
      - --providers.docker
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
    ports:
      - '80:80'
      - '443:443'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    depends_on:
      - grimoire
  grimoire:
    image: goniszewski/grimoire:latest
    container_name: grimoire
    restart: unless-stopped
    env_file: .env
    # network_mode: bridge
    labels:
      - traefik.http.routers.grimoire.rule=Host(`grimoire.[your-domain.com]`)
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '$PORT:$PORT'
    volumes:
      grimoire_data:

If everything looks good, let's move on to the next step!

Step 5: Pull and run the containers​

Now we'll use the Docker Compose to pull the containers and run the application:

docker compose up

Or if you want to run it in the background:

docker compose up -d

Step 6: Open the application in your browser​

Well done! Now go to https://grimoire.[your-domain.com] and check if everything works as expected.

Want to have more control?​

You can add some extra features with Traefik labels:

Rate Limiting​

To prevent abuse, you can add rate limiting to your Grimoire instance:

labels:
  - traefik.http.middlewares.grimoire-ratelimit.ratelimit.average=100
  - traefik.http.middlewares.grimoire-ratelimit.ratelimit.burst=50
  - traefik.http.routers.grimoire.middlewares=grimoire-ratelimit

This configuration limits requests to an average of 100 per second, with a burst of up to 50 requests.

IP Whitelisting​

If you want to restrict access to Grimoire to specific IP addresses:

labels:
  - traefik.http.middlewares.grimoire-ipwhitelist.ipwhitelist.sourcerange=192.168.1.7,172.16.0.0/16
  - traefik.http.routers.grimoire.middlewares=grimoire-ipwhitelist

This allows access only from the IP 192.168.1.7 and the 172.16.0.0/16 subnet.

You can add these labels to the grimoire service in your docker-compose.yml file to implement these features.

Troubleshooting​

Here are some common issues you might encounter and their solutions:

Grimoire is not accessible through the reverse proxy​

  1. Check if the Grimoire container is running:

    docker ps | grep grimoire

    If it's not listed, try restarting the container:

    docker compose up -d grimoire

  2. Verify Traefik labels are correct: Ensure the traefik.http.routers.grimoire.rule label in your docker-compose.yml matches your domain.

  3. Check Traefik logs:

    docker logs reverse-proxy

    Look for any errors related to routing or certificate issues.

SSL certificate issues​

  1. Ensure your domain's DNS is properly configured and pointing to your server.

  2. Check Traefik logs for certificate-related errors:

    docker logs reverse-proxy | grep -i "certificate"

  3. Verify that ports 80 and 443 are open on your firewall.

Container fails to start​

  1. Check container logs:

    docker logs grimoire

  2. Ensure all required environment variables are set correctly in your compose file.

  3. Verify that the grimoire_data volume has correct permissions.

If you're still experiencing issues, please check the Grimoire GitHub Issues or create a new issue with details about your setup and the problem you're facing.