Install with Docker

Docker is the recommended way to run Spug. The official image bundles Nginx, Redis and every background service; the database runs in a separate MariaDB container and everything starts with a single docker compose command.

Requirements

• Docker 20.10 or later (with the docker compose plugin)
• A modern browser (latest Chrome / Edge / Firefox / Safari)

Supported CPU architectures

On Docker Hub both tags of openspug/spug-service, 4.0 (the 4.0 release this guide covers, current code version v4.0.1) and latest (3.x, not 4.0), are published for amd64 and arm64, and Docker picks the architecture of the host automatically, so ARM64 hosts (Kunpeng, Phytium, Raspberry Pi, Apple Silicon, ...) work out of the box. ARM64 hosts must pull from Docker Hub; the Alibaba Cloud registry currently only has x86 images of 3.x. 32-bit ARM (armv7) is not supported.

Installation

The steps below use Ubuntu 22.04 / CentOS 7; only the Docker installation command differs on other Linux distributions.

1. Install Docker

Note

Skip this step if Docker is already installed. For other systems see the Docker documentation.

# CentOS / RHEL
yum install -y yum-utils
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
yum install -y docker-ce docker-compose-plugin
systemctl enable docker
systemctl start docker

# Ubuntu / Debian
curl -fsSL https://get.docker.com | bash
systemctl enable docker
systemctl start docker

2. Create docker-compose.yml

mkdir -p /data/spug && cd /data/spug
vi docker-compose.yml

version: "3.3"
services:
  db:
    image: mariadb:10.8
    container_name: spug-db
    restart: always
    command: --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
    volumes:
      - /data/spug/mysql:/var/lib/mysql
    environment:
      - MYSQL_DATABASE=spug
      - MYSQL_USER=spug
      - MYSQL_PASSWORD=spug.cc
      - MYSQL_ROOT_PASSWORD=spug.cc
  spug:
    image: openspug/spug-service:4.0
    container_name: spug
    privileged: true
    restart: always
    volumes:
      - /data/spug/service:/data/spug
      - /data/spug/repos:/data/repos
    ports:
      # if port 80 is taken, map another one, e.g. - "8000:80"
      - "80:80"
    environment:
      - SPUG_DOCKER_VERSION=v4.0.1
      - MYSQL_DATABASE=spug
      - MYSQL_USER=spug
      - MYSQL_PASSWORD=spug.cc
      - MYSQL_HOST=db
      - MYSQL_PORT=3306
    depends_on:
      - db

What the settings mean:

Path / setting	Description
/data/spug/mysql	Database files, must be persisted
/data/spug/service	Spug program directory (/data/spug inside the container); on first start the version selected by SPUG_DOCKER_VERSION is cloned from gitee, the front-end bundle is downloaded and spug_api/spug/overrides.py is generated
/data/spug/repos	Git checkouts and build artifacts of standard deployments
SPUG_DOCKER_VERSION	Code version (git tag) fetched on first start; it must match the image version, use v4.0.1 with the 4.0 image. There is no default: without it the container exits while cloning and keeps restarting
MYSQL_*	Database connection, must match the db service; can point to your own MySQL instead, see external MySQL
privileged: true	Required by file distribution, which mounts remote directories with sshfs

Registry mirror

The Alibaba Cloud registry registry.cn-hangzhou.aliyuncs.com/openspug/spug-service currently only provides x86 images of 3.x, with neither a 4.0 tag nor ARM64 builds, so do not replace the image above with the Alibaba Cloud address. If pulling from Docker Hub fails because of network restrictions, configure a Docker Hub registry mirror for the Docker daemon (registry-mirrors in /etc/docker/daemon.json, then restart Docker); the image names in docker-compose.yml stay unchanged.

3. Start the containers

docker compose up -d

Note

With the legacy standalone docker-compose binary run docker-compose up -d instead.

The first start needs internet access

Unlike the 3.x image, which ships with the code built in, the 4.0 image does not contain the code: on first start the container clones the version selected by SPUG_DOCKER_VERSION from gitee.com and downloads the matching front-end bundle from cdn.spug.cc. Make sure the server can reach both hosts; the first start cannot complete on an isolated / offline network. Fetching the code and initializing the database usually takes 10 to 30 seconds (follow the container log with docker logs -f spug); run step 4 once it is done.

4. Initialize

The command below creates the database tables and an administrator account with user name admin and password spug.cc; replace them with your own values.

docker exec spug init_spug admin spug.cc

Tip

On the very first start wait until the code has been fetched and the database is ready (usually 10 to 30 seconds) before running the command. If it fails with can't open file '/data/spug/spug_api/manage.py' (the code is still being fetched) or Can't connect to MySQL server on 'db:3306' (the database is still initializing), wait a few seconds and run it again.

5. Open Spug

Open http://<server-ip>:80 in the browser and log in with the account created in step 4. The globe icon in the header switches between English and Chinese.

6. Upgrading

The running version is shown under System / Settings / About, the latest version is listed in the change log, and the upgrade procedure is described in Upgrade.

Day-to-day commands

# follow the container log
docker logs -f spug

# open a shell in the container
docker exec -it spug bash

# processes of every service (gunicorn = api, daphne = ws, runworker / runmonitor / runscheduler, nginx, redis)
# supervisord in the 4.0 image has no RPC interface, so supervisorctl does not work; restart the container instead
docker exec spug ps -ef

# restart the container
docker restart spug

Directory layout inside the container:

Path	Description
/data/spug/spug_api	Back-end code, local overrides in spug/overrides.py
/data/spug/spug_api/logs	Log files of the background services
/data/spug/env	Environment file of the 3.x image; the 4.0 image no longer reads it. Put container-wide variables into the environment of docker-compose.yml, see command not found
/etc/nginx/nginx.conf	Nginx configuration
/etc/supervisord.conf	Background service definitions; supervisord starts nginx, redis and the Spug services directly from this file

Security recommendations

• Do not expose Spug directly to the internet. If public access is unavoidable, restrict source IPs with a firewall and enable login MFA under System / Settings / Security Settings.
• When you put another reverse proxy (Nginx etc.) in front of the container's port 80, forward the X-Forwarded-For header and enable WebSocket forwarding, see WebSocket.
• Change the default database password in docker-compose.yml.