Skip to main content
🚀 Unlock Premium Features with the OpenPanel Enterprise Annual License Secure Your Discount
OpenPanelDocumentation
Version: 1.7.50

Adding custom docker images for OpenPanel users

Each user has a Docker service running in Rootless mode and a single docker-compose.yml file that has all their services defined.

For each user you can edit their /home/USER/docker-compose.yml file to specify custom services.

Default services​

To edit services for all new users that you create, edit the template files:

  • /etc/openpanel/docker/compose/1.0/docker-compose.yml - services for users, volumes and networks.
  • /etc/openpanel/docker/compose/1.0/.env - limits for services.

Guidelines​

You can add any Docker image by including its Compose configuration. However, there are a few important rules to follow so that OpenPanel can:

  • Recognize the service as valid
  • Allow editing of resource limits from the GUI
  • Enable service start/stop control from the GUI
  • Monitor usage statistics
  • Enforce resource restrictions

Make sure your service definition follows the required structure to ensure full OpenPanel integration.

NameDescriptionExample
service nameThe service name must exactly match the container_name and cannot contain spaces.For uptimekuma: container_name: uptimekuma
env variablesAll variables in the .env file must start with the service name in uppercase, followed by an underscore. Each service must define _CPU and _RAM to allow OpenPanel to restrict and monitor resource usage.UPTIMEKUMA_VERSION="1" UPTIMEKUMA_CPU="0.5" UPTIMEKUMA_RAM="0.5G"
image tagThe image tag should be a variable, allowing it to be changed via the OpenPanel UI. If not provided, a fallback value is used.image: louislam/uptime-kuma:${UPTIMEKUMA_VERSION:-1}
volumesMounting host OS paths can expose the server. Use relative paths (e.g., ./data) for app data. To use existing data like /var/www/html/, mount the appropriate volume. If Docker socket access is needed, mount /hostfs/run/user/${USER_ID}/docker.sock as read-only to prevent privilege escalation.- ./data:/app/data - html_data:/var/www/html/ - /hostfs/run/user/${USER_ID}/docker.sock:/var/run/docker.sock:ro
resourcesDefine cpus, memory, and pids under the deploy.resources.limits section. Without pids, services are vulnerable to fork bombs. Use variables with fallback values for cpus and memory.cpus: "${BUSYBOX_CPU:-0.1}" memory: "${BUSYBOX_RAM:-0.1G}" pids: 100
networksOnly add networks if the service needs access to other containers. Use either www or db networks. www is for app/webserver access; db is for database-only access.- www - db
environmentUse the environment section to pass custom environment variables.EULA: "TRUE" ENABLE_QUERY: "${MINECRAFT_ENABLE_QUERY:-true}"
portsOnly define ports if external access is required. For internal-only services (e.g., Redis, Memcached), do not expose ports.- "${MYSQL_PORT}" - "${MINECRAFT_PORT:-25565}:25565"
labelsLabels are optional and ignored by OpenPanel but can be used for external tools or metadata.- docker-volume-backup.archive-pre=/bin/sh -c '/dump.sh'
healthcheckOptional. If defined, OpenPanel respects the health check and uses it to manage restarts.test: ['CMD-SHELL', 'mysqladmin ping -h localhost'] interval: 1s timeout: 5s retries: 10
restart policyrestart policy should be explicitly set to unless-stopped so that OpenPanel can auto-restart services in case of failure, except when user account is suspended.restart: unless-stopped

Examples​

These examples are drop-in snippets you can insert into your files to add a new service for an OpenPanel user.

FileBrowser​

To add FileBrowser as a service for user in OpenPanel:

add to .env file:

# FILEBROWSER
FILEBROWSER_VERSION="s6"
FILEBROWSER_CPU="0.25"
FILEBROWSER_RAM="0.35"

add to docker-compose.yml file in the services section:

  filebrowser:
    image: filebrowser/filebrowser:${FILEBROWSER_VERSION:-s6}
    container_name: filebrowser
    volumes:
      - html_data:/srv
      - ./filebrowser/config/:/config/
      - ./filebrowser/database/:/database/
    environment:
      - PUID=${USER_ID:-0}
      - PGID=${USER_ID:-0}
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "${FILEBROWSER_CPU:-0.35}"
          memory: "${FILEBROWSER_RAM:-0.35G}"   
          pids: 100
    networks:
      - www

Minecraft​

To add Minecraft as a service for user in OpenPanel:

add to .env file:

# MINECRAFT
MINECRAFT_VERSION="latest"
MINECRAFT_PORT="25565"
MINECRAFT_CPU="1.0"
MINECRAFT_RAM="1.0G"
MINECRAFT_ENABLE_QUERY="true"
MINECRAFT_MAX_PLAYERS="20"
MINECRAFT_MAX_WORLD_SIZE="10000"
MINECRAFT_ALLOW_NETHER="false"
MINECRAFT_ANNOUNCE_PLAYER_ACHIEVEMENTS="false"
MINECRAFT_ENABLE_COMMAND_BLOCK="false"

add to docker-compose.yml file in the volumes section:

  mc_data:
    driver: local
    labels:
      description: "This volume holds the minecraft data directory."
      purpose: "storage"

add to docker-compose.yml file in the services section:

  minecraft:
    image: itzg/minecraft-server:${MINECRAFT_VERSION:-latest}
    container_name: minecraft
    tty: true
    stdin_open: true
    ports:
      - "${MINECRAFT_PORT:-25565}:25565"
    environment:
      EULA: "TRUE"
      ENABLE_QUERY: "${MINECRAFT_ENABLE_QUERY:-true}"
      QUERY_PORT: "${MINECRAFT_PORT:-25565}"
    volumes:
      - mc_data:/data
    deploy:
      resources:
        limits:
          cpus: "${MINECRAFT_CPU:-1.0}"
          memory: "${MINECRAFT_RAM:-1.0G}"
          pids: 100
    healthcheck:
      test: mc-health
      start_period: 1m
      interval: 5s
      retries: 20
    networks:
      - www

MsSQL​

To add MsSQL as a service for user in OpenPanel:

add to .env file:

# MSSQL
MSSQL_IMAGE="mcr.microsoft.com/mssql/server"
MSSQL_VERSION="latest"
MSSQL_PID="Standard"
MSSQL_PORT="0:1433"
MSSQL_CPU="1.0"
MSSQL_RAM="1.0G"
MSSQL_SA_PASSWORD="rootpassword"

add to docker-compose.yml file in the volumes section:

  mssql_data:
    driver: local
    labels:
      description: "This volume holds the MSSQL databases."
      purpose: "database"

add to docker-compose.yml file in the services section:

  mssql:
    image: ${MSSQL_IMAGE}:${MSSQL_VERSION:-latest}
    container_name: mssql
    restart: unless-stopped
    environment:
      ACCEPT_EULA: "Y"
      MSSQL_SA_PASSWORD: ${MSSQL_SA_PASSWORD:-StrongPassword!}
      MSSQL_PID: ${MSSQL_PID:-Developer}  # Options: Developer, Express, Standard, Enterprise
    ports:
      - "${MSSQL_PORT}"
    volumes:
      - mssql_data:/var/opt/mssql                                      # MSSQL data
      - ./sockets/mssql:/var/opt/mssql/sockets          # MSSQL socket
      - ./mssql.conf:/etc/mssql/mssql.conf:ro           # Custom MSSQL config
    deploy:
      resources:
        limits:
          cpus: "${MSSQL_CPU:-1}"
          memory: "${MSSQL_RAM:-2G}"
          pids: 100
    networks:
      - db
    healthcheck:
      test: ['CMD-SHELL', 'sqlcmd -S localhost -U sa -P "$$MSSQL_SA_PASSWORD" -Q "SELECT 1" || exit 1']
      interval: 10s
      timeout: 5s
      retries: 5

UptimeKuma​

To add UtimeKuma as a service for user in OpenPanel:

add to .env file:

# UPTIMEKUMA
UPTIMEKUMA_VERSION="1"
UPTIMEKUMA_CPU="0.5"
UPTIMEKUMA_RAM="0.5G"

add to docker-compose.yml file in the services section:

  uptimekuma:
    image: louislam/uptime-kuma:${UPTIMEKUMA_VERSION:-1}
    container_name: uptimekuma
    volumes:
      - ./data:/app/data
      - /hostfs/run/user/${USER_ID}/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "${UPTIMEKUMA_CPU:-0.35}"
          memory: "${UPTIMEKUMA_RAM:-0.35G}"   
          pids: 100
    networks:
      - www

BusyBox​

This example adds busybox container, its an example on how to add any docker compose service:

add to .env file:

# BUSYBOX
BUSYBOX_CPU="0.1"
BUSYBOX_RAM="0.1G"

add to docker-compose.yml file in the services section:

  busybox:
    image: busybox
    container_name: busybox          
    restart: unless-stopped
    working_dir: /var/www/html
    deploy:
      resources:
        limits:
          cpus: "${BUSYBOX_CPU:-0.1}"
          memory: "${BUSYBOX_RAM:-0.1G}"   
          pids: 100
    volumes:
      - html_data:/var/www/html/
Previous
User Isolation
Next
Unlimited CPU&RAM
Was this helpful?