maxun/docs/self-hosting-docker.md

Self hosting docker guide

So you want to create a bot? Let's get you started!

Requirements (not covered)

• Webserver (Apache2, nginx, etc.)
• SSL Certificates (letsencrypt, zerossl, etc)
• A sub-domain to host maxun i.e. maxun.my.domain
• Docker
• Docker compose
• Probably others...

Guide

For this guide, we assume that before you start, you have a dedicated docker folder to house config files and everything else we need for persistence between docker container reboots and updates. The path in this guide is /home/$USER/Docker/maxun.

1. Change directory into your docker folder cd /home/$USER/Docker/

2. Create a new directory for maxun and all the required sub-folders for our docker services mkdir -p maxun/{db,minio,redis}

3. Change directory to enter the newly created folder cd maxun

4. Create your .env file. Use either option below.

   Option A — generate it automatically (recommended)

   From the root of a cloned Maxun repo (maxun/), run the generator (it lives in docs/):

   bash docs/generate-env.sh
   

   ex: ./docs/generate-env.sh (if your terminal runs scripts using ./)

   If your current directory is maxun/docs instead, run:

   bash generate-env.sh
   

   ex: ./generate-env.sh (if your terminal runs scripts using ./)

   It writes .env into the current directory, so run it from the same folder your docker-compose.yml will live in. Requires openssl and bash — on Windows, use WSL or Git Bash.

   Option B — write it yourself

   Run each command below and paste its output after the matching =:

   openssl rand -base64 48   # JWT_SECRET
   openssl rand -base64 24   # DB_PASSWORD
   openssl rand -hex 32      # ENCRYPTION_KEY  (must be 64 hex characters)
   openssl rand -base64 48   # SESSION_SECRET
   openssl rand -base64 24   # MINIO_SECRET_KEY
   

   Then create the file with nano .env and paste in the following, replacing each placeholder with the matching output above:

   NODE_ENV=production
   JWT_SECRET=<output of first command>
   DB_NAME=maxun
   DB_USER=postgres
   DB_PASSWORD=<output of second command>
   DB_HOST=postgres
   DB_PORT=5432
   ENCRYPTION_KEY=<output of third command>
   SESSION_SECRET=<output of fourth command>
   MINIO_ENDPOINT=minio
   MINIO_PORT=9000
   MINIO_CONSOLE_PORT=9001
   MINIO_ACCESS_KEY=minio
   MINIO_SECRET_KEY=<output of fifth command>
   REDIS_HOST=maxun-redis
   REDIS_PORT=6379
   REDIS_PASSWORD=
   BACKEND_PORT=8080
   FRONTEND_PORT=5173
   BACKEND_URL=https://maxun.my.domain
   PUBLIC_URL=https://maxun.my.domain
   VITE_BACKEND_URL=https://maxun.my.domain
   VITE_PUBLIC_URL=https://maxun.my.domain
   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   GOOGLE_REDIRECT_URI=
   AIRTABLE_CLIENT_ID=
   AIRTABLE_REDIRECT_URI=
   MAXUN_TELEMETRY=true
   

   Save with Ctrl + X, Y, Enter.

   Do not put a literal dollar sign in any value. Docker Compose reads it as a variable reference and silently drops it, leaving you with a shorter secret than you pasted. Double it to escape one.

5. Whichever option you used, READ the file and change the variables to match your environment — in particular BACKEND_URL, PUBLIC_URL, VITE_BACKEND_URL, VITE_PUBLIC_URL, and any ports you need to change (i.e. BACKEND_PORT=30000).

6. Create a file for docker compose nano docker-compose.yml with the following contents:

services:
  postgres:
    image: postgres:17
    container_name: maxun-postgres
    mem_limit: 512M
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - /home/$USER/Docker/maxun/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  redis:
    image: docker.io/library/redis:7
    container_name: maxun-redis
    restart: always
    mem_limit: 128M
    volumes:
      - /home/$USER/Docker/maxun/redis:/data

  minio:
    image: minio/minio
    container_name: maxun-minio
    mem_limit: 512M
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    command: server /data --console-address :${MINIO_CONSOLE_PORT:-9001}
    volumes:
      - /home/$USER/Docker/maxun/minio:/data

  backend:
    image: getmaxun/maxun-backend:latest
    container_name: maxun-backend
    ports:
      - "127.0.0.1:${BACKEND_PORT:-8080}:${BACKEND_PORT:-8080}"
    env_file: .env
    environment:
      BACKEND_URL: ${BACKEND_URL}
      PLAYWRIGHT_BROWSERS_PATH: /ms-playwright
      PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: 0
      # DEBUG: pw:api
      # PWDEBUG: 1  # Enables debugging
      CHROMIUM_FLAGS: '--disable-gpu --no-sandbox --headless=new'
    security_opt:
      - seccomp=unconfined  # This might help with browser sandbox issues
    shm_size: '2gb'
    mem_limit: 4g
    depends_on:
      - postgres
      - minio
    volumes:
      - /var/run/dbus:/var/run/dbus

  frontend:
    image: getmaxun/maxun-frontend:latest
    container_name: maxun-frontend
    mem_limit: 512M
    ports:
      - "127.0.0.1:${FRONTEND_PORT:-5173}:5173"
    env_file: .env
    environment:
      PUBLIC_URL: ${PUBLIC_URL}
      BACKEND_URL: ${BACKEND_URL}
    depends_on:
      - backend

7. Ctrl + x, Y, Enter will save your changes
8. This particular setup is "production ready" meaning that maxun is only accessible from localhost. You must configure a reverse proxy to access it!
9. Start maxun sudo docker compose up -d or sudo docker-compose up -d
10. Wait 30 seconds for everything to come up
11. Access your maxun instance at http://localhost:5173 if using defaults

Next steps

You will want to configure a reverse proxy. Click on a link below to check out some examples.

• Nginx