Development Setup

This guide sets up a development environment for people who want to extend Spug. For production use the Docker install, or a manual deployment if necessary.

Requirements

• Python 3.8 or later
• Node.js 18 or later (20 LTS recommended; the front-end npm start / npm run build scripts pass --openssl-legacy-provider, which Node 16 and older reject)
• Redis 5.0 or later
• Git 2.17.0 or later (needed by standard deploys)
• A modern browser

Project layout

Directory	Description
spug_api	back-end, Django 4.2 + channels 4; modules live in apps/ (host, exec, deploy, pipeline, credential, schedule, monitor, alarm, config, setting, ...)
spug_web	front-end, React 16 + antd 4 + mobx; pages in src/pages, English dictionaries in src/locales/en
spug_web2	early version of a new front-end based on Vite + React 18 + antd 5, not in use yet; 4.0 still ships spug_web
docs/docker	build files of the official Docker image

Steps

The steps assume the project is installed under /data/spug on macOS.

1. Clone the repository

git clone https://github.com/openspug/spug /data/spug

2. Create the Python environment

cd /data/spug/spug_api
python3 -m venv venv
source venv/bin/activate
pip install -U pip setuptools
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

3. Initialize the database

SQLite is used by default.

python manage.py updatedb

4. Create the administrator account

python manage.py user add -u admin -p spug.cc -s -n Administrator

# -u user name
# -p password
# -s super administrator
# -n display name

5. Start the API development server

python manage.py runserver

runserver serves both the HTTP API and WebSocket through daphne (default http://127.0.0.1:8000), so the web terminal and the live consoles of batch execution, deployments and pipelines work in development as well.

6. Install front-end dependencies

yarn or pnpm work as well as npm.

cd /data/spug/spug_web
npm install --registry=https://registry.npmmirror.com

7. Start the front-end

npm start

The front-end proxies /api requests (including WebSocket) to port 8000 of the back-end through src/setupProxy.js.

8. Open Spug

npm start normally opens the browser automatically; otherwise open http://localhost:3000. If you followed the steps above, log in with the account created in step 4:

user name: admin
password: spug.cc

9. Optional services

Spug is now usable, but batch execution, deployments and pipelines need runworker, scheduled tasks need runscheduler and monitoring needs runmonitor; start them as described in Development FAQ.

10. Building the front-end

cd /data/spug/spug_web
npm run build

The output goes to spug_web/build and is served by Nginx in manual deployments.

Common installation problems

See Installation FAQ