# Technical Documentation: openspug/spug

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/openspug/spug)

### Overview (`README.md`)

English | [简体中文](./README-zh_CN.md) 

<h1 align="center">Spug</h1>

<div align="center">

Spug is a lightweight agent-free automatic operation and maintenance platform designed for small and medium-sized enterprises. It integrates host management, host batch execution, host online terminal, file management, application release and deployment, pipelines, online task planning, configuration center, monitoring, alarm and so on.

</div>



## Demo

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

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.

```bash
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](./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](https://ops.spug.cc/en/docs/install-docker/).

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](https://www.spug.cc/cloud?lang=en&ref=github) 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 

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](https://push.spug.cc)


## Features

- **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

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

## Documentation

- 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

### Workbench


### Dashboard


### Host Management


#### Host Online Terminal


#### File Online Upload and Download


#### Host Batch Execution



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






### Application Release




### Task Planning


### Configuration Center


### Monitoring and Alarm



 
## License & Copyright
[AGPL-3.0](https://opensource.org/licenses/AGPL-3.0)

---

### Overview (`spug_web2/README.md`)

# 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](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh

---

### FQA (`docs/FQA.md`)

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

---

### I18n (`docs/i18n.md`)

# 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

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.

```js
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

| Path | Purpose |
| --- | --- |
| `spug_web/src/libs/i18n.js` | `t()`, `getLanguage()`, `setLanguage()`, `langMode`, `isEN` |
| `spug_web/src/locales/en/index.js` | merges every module dictionary |
| `spug_web/src/locales/en/base.js` | shared glossary, merged **last** so common terms stay consistent |
| `spug_web/src/locales/en/<module>.js` | per-module dictionaries (host, deploy_app, pipeline, …) |

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

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

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`)

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