Technical Documentation: openspug/spug

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

English | 简体中文

Spug

Demo Copy Chapter

Demo: https://demo.spug.cc (username admin, password spug.cc)

The demo environment runs the latest version and resets its data every hour, both the English and the Simplified Chinese interface are available from the globe icon in the header.

Quick start Copy Chapter

You need Docker 20.10.10 or later with the Compose plugin. The image runs on amd64 and arm64 and has the back end and the web UI built in, so nothing is downloaded when the container starts.

curl -fsSLO https://raw.githubusercontent.com/openspug/spug/4.0/docker-compose.yml
docker compose up -d
docker compose logs spug | grep password

Open http://<your-server>/ and log in as admin with the password printed by the last command (it is generated on the first start). Time zone, port and database password are set in docker-compose.yml, and the image is also published as ghcr.io/openspug/spug. For a quick look without the database container, docker run -d --name spug -p 8080:80 openspug/spug:4.1 starts a single container on SQLite (get the password with docker logs spug | grep password). Upgrades and other ways to install are covered in the installation guide.

Would you use Spug without maintaining the control panel yourself? Spug Cloud is being researched and is not available yet. The proposed service would host the control panel and connect to your servers over SSH, at a planned $4.9 per server/month. If you would consider trying it at that price, join the research waitlist and tell us how many servers you manage and what you would use it for. Self-hosted Spug remains free and open source.

🔥Push Assistant Copy Chapter

Push Assistant is a message push platform that integrates multiple channels such as telephone, SMS, email, Feishu, DingTalk, WeChat, and WeChat Work. It can realize telephone and SMS alarms of Zabbix, Prometheus, Nightingale and other monitoring systems in 3 minutes. Click to experience: https://push.spug.cc

Features Copy Chapter

• Host Management: Manage hosts by group, import them from cloud providers or an Excel file, and check connectivity in batch
• Host Batch Execution: Support host batch online command execution, with parameterized commands, reusable templates and execution history
• Host Online Terminal: The host supports browser online terminal login
• Host File Management: Support host files online upload and download
• File Distribution: Distribute files and directories from one host to many hosts
• Build and Deploy: Support application custom build deployment, with review flow, canary release and rollback
• Pipelines: Orchestrate parameter, build, remote command, data transfer, data upload and DingTalk / Feishu / WeChat Work / Push Assistant notification nodes into a workflow, with conditional branches and a live console
• Task Planning: It supports online configuration of crontab, interval and other task schedules
• Configuration Center: Support KV, text, json and other formats online configuration
• Monitoring Center: Support site, port, process, ping, custom script and other monitoring
• Alarm Center: Support email, WeChat, DingTalk, WeChat Work, Feishu and other alarm methods
• Credential Management: Keep passwords and private keys in one place and share them across hosts
• Permission Control: Fine-grained role and permission control, LDAP login and MFA are supported
• Bilingual UI: Full English and Simplified Chinese interface, switchable from the header
• Elegant and beautiful: UI interface based on Ant Design
• Open source and free: The front-end and back-end code is completely open source

Environment Copy Chapter

• Python 3.8+
• Django 4.2
• Node.js 18+
• React 16.13
• Redis 5.0+

Documentation Copy Chapter

• Installation: https://ops.spug.cc/en/docs/install-docker/
• User guide: https://ops.spug.cc/en/docs/about-spug/
• Change log: https://ops.spug.cc/en/docs/change-log/
• FAQ: https://ops.spug.cc/en/docs/faq/
• Issues: https://github.com/openspug/spug/issues (English or Chinese are both welcome)
• Spug Push: https://push.spug.cc

PreView Copy Chapter

Workbench Copy Section

Dashboard Copy Section

Host Management Copy Section

Host Online Terminal

File Online Upload and Download

Host Batch Execution

Pipelines Copy Section

Orchestrate build, command, data transfer, upload and notification nodes into a workflow.

Application Release Copy Section

Task Planning Copy Section

Configuration Center Copy Section

Monitoring and Alarm Copy Section

License & Copyright Copy Chapter

AGPL-3.0

Overview (`spug_web2/README.md`) Copy Section

React + Vite

This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.

Currently, two official plugins are available:

• @vitejs/plugin-react uses Babel for Fast Refresh
• @vitejs/plugin-react-swc uses SWC for Fast Refresh

FQA (`docs/FQA.md`) Copy Section

install mysqlclient Copy Section

# for centos 7
yum install mariadb-devel python3-devel gcc
pip install mysqlclient

I18n (`docs/i18n.md`) Copy Section

Internationalization (i18n)

Spug ships with a Simplified Chinese and an English interface. Users switch
languages from the globe icon in the header (or on the login page); the choice
is stored in localStorage under spug:language and the page reloads so that
Ant Design and moment pick up the new locale too.

How it works Copy Chapter

Chinese is the source language: the original Chinese text is the translation
key. t() looks the key up in the English dictionary when the UI is in English
mode, and returns the key unchanged in Chinese mode. That means the Chinese UI
can never regress from a missing or wrong translation.

import { t } from 'libs';

t('新建')                       // zh: '新建'          en: 'New'
t('确定要删除【{}】?', name)     // {} placeholders are filled in both languages

Only user-visible text is wrapped. Values sent to or compared against the
backend (<Select.Option value="branch">, status === '3', localStorage keys)
stay untouched.

Frontend layout Copy Chapter

Add a translation by putting the exact Chinese string as the key in the
dictionary of the module you are working on. If the term is already in
base.js, do not redefine it — base.js wins on conflicts.

Backend messages Copy Chapter

API error messages and the *_alias display values of model choices are
translated in spug_api/libs/locale.py:

• MESSAGES — exact-match error strings.
• _PATTERNS — regexes for messages built with f-strings, e.g.
  已存在的主机名称【web-01】.
• CHOICES — display values of model field choices (deploy status, monitor
  type, …), returned to the client through status_alias, type_alias, etc.

libs/middleware.py:TranslateMiddleware applies them when the request carries
X-Language: en (the frontend sets this header on every /api/ call). Requests
without the header — or with zh — are passed through untouched.

Adding a new language Copy Chapter

1. Copy spug_web/src/locales/en/ to spug_web/src/locales/<lang>/ and
   translate the values.
2. In libs/i18n.js load the dictionary for that language and extend
   getLanguage() / the language menu in layout/Header.js and
   pages/login/index.js.
3. Map the language to an Ant Design locale and a moment locale in
   spug_web/src/index.js.
4. Optionally add a matching dictionary next to libs/locale.py for backend
   messages and dispatch on the X-Language value in TranslateMiddleware.

Docker Docker Compose.Yml (`docs/docker/docker-compose.yml`) Copy Section

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:
# 镜像只包含运行环境（Python/Django 4.2 等），按 4.0 大版本维护；具体代码版本由下面的
# SPUG_DOCKER_VERSION 决定，4.0.x 的补丁版本只需改该变量，不必换镜像
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:
# 如果80端口被占用可替换为其他端口，例如: - "8000:80"
- "80:80"
environment:
# 代码版本（git 标签名），容器首次启动时按此值从 gitee 拉取代码并下载
# 同名前端产物 https://cdn.spug.cc/spug/web_${SPUG_DOCKER_VERSION}.tar.gz，
# 因此标签与 CDN 文件名必须配套。4.0 镜像预装 Django 4.2 / channels 4，
# 只能运行 4.x 代码，不能用于 3.x 版本。
- 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

--- METRICS ---

• Files Extracted: 5
• Estimated Token Budget: ~2465 tokens
• Canonical Reference: https://codewiki.google/github.com/openspug/spug