Skip to main content
Version: 4.x

Installation FAQ

python manage.py updatedb fails​

Usually one of the following:

  • The Python version is too old; Spug 4.0 requires Python 3.8 or later.
  • Dependency versions do not match. Install them with pip install -r requirements.txt as documented (Django 4.2, channels 4, ...) and do not up- or downgrade single packages.
  • When using SQLite, the system SQLite is too old; Django 4.2 needs SQLite 3.21.0 or later. Use MySQL / MariaDB in production.

Nginx reports permission denied for the front-end files​

Check whether selinux is enabled. Run setenforce 0 to disable it temporarily and try again.

Login fails with 504 Gateway Timeout​

Make sure the api service is running. In a manual deployment it listens on 127.0.0.1:9001 (see spug_api/tools/start-api.sh) and the /api/ location in Nginx must proxy to that address. In development the front-end proxies to http://127.0.0.1:8000 through spug_web/src/setupProxy.js, so python manage.py runserver must listen on that port.

Login fails with 502 Bad Gateway​

Make sure the api service is running and the nginx configuration is correct. If the nginx log shows 13: Permission denied, disable selinux and try again.

Login fails with Exception: Error 61 connecting to 127.0.0.1:6379. Connection refused.​

Redis (5.0 or later) must be installed. If it does not listen on 127.0.0.1, set its address in spug_api/spug/overrides.py; both CACHES and CHANNEL_LAYERS use Redis, see below.

The host console, deploy page or pipeline console shows no output​

Real-time output is pushed over WebSocket. Make sure the spug-ws service (daphne) is running and that Nginx forwards /api/ws/ as WebSocket, see WebSocket.

Adding a host fails with Exception: not a vaild RSA private key file​

The key pair generated by Spug could not be validated. Check that the private key uploaded under System / Settings / SSH Key Settings is valid (RSA, Ed25519, ECDSA and DSA are supported; Spug generates 2048-bit RSA keys), or clear it and let Spug generate a new pair.

How do I use a Redis server with a password?​

Assuming the password is foo123, add the following to spug_api/spug/overrides.py (recommended) or settings.py (harder to upgrade later) and restart the services.

Tip

Custom settings go into spug_api/spug/overrides.py, which overrides the defaults. With the Docker install the file is at /data/spug/service/spug_api/spug/overrides.py on the host. Settings in overrides.py replace the whole dictionary instead of being merged, so keep the remaining keys from settings.py (KEY_PREFIX of CACHES; prefix / capacity / expiry of CHANNEL_LAYERS) and only change the address and password.

vi spug_api/spug/overrides.py
CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://:foo123@127.0.0.1:6379/1",
        "KEY_PREFIX": "spug",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        }
    }
}

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {
            "hosts": ["redis://:foo123@127.0.0.1:6379/0"],
            "prefix": "spug:channel",
            "capacity": 1000,
            "expiry": 120,
        },
    },
}

Using an external MySQL with the Docker install​

The Docker install takes its database connection entirely from the environment variables of the spug service in docker-compose.yml. To use an external database:

  1. Create a database and user with the utf8mb4 charset on your MySQL / MariaDB server.
  2. Remove the db service and the depends_on entry of the spug service from docker-compose.yml.
  3. Set MYSQL_HOST, MYSQL_PORT, MYSQL_DATABASE, MYSQL_USER and MYSQL_PASSWORD of the spug service to the external database.
  4. Run docker compose up -d and then the initialization command.
Note

The container generates /data/spug/spug_api/spug/overrides.py from the environment variables on its very first start and does not overwrite it afterwards. If the container has already been initialized, edit the DATABASES section of /data/spug/service/spug_api/spug/overrides.py on the host and restart the container. When migrating data, read the upgrade notes first so that future upgrades keep working.

Using SQL Server​

Thanks to @xiongwu1 for the contribution, see #38.