Back up and upgrade the panel

In this guide you back up what a panel node can’t be rebuilt without, upgrade the panel to a new release, and roll the upgrade back if needed.

Prerequisites

Root on the panel host.
A panel installed with install-prebuilt.sh or install.sh.

Steps

1. Know what to back up

What	Where	Why
Panel database	the Postgres in `/etc/gisila/database.yaml`	Users, teams, apps, deployments, encrypted env vars.
Secret key	`/etc/gisila/secret.key`	Decrypts env var values and deployment snapshots. Without it those are lost. Back it up together with the database.
Panel config	`/etc/gisila/.env`, `/etc/gisila/database.yaml`	JWT secret, Redis and database connection.
App data	`/srv/apps/<user>/shared/`	Anything your apps write, such as media uploads.
App databases	panel-managed Postgres/Mongo instances	Use the panel’s scheduled backups, then copy them off the host from `/var/lib/gisila/backups`.
Certificates	`/etc/letsencrypt`	Optional. They can be re-issued.

A minimal nightly backup of the panel itself:

#!/usr/bin/env bash
set -euo pipefail
STAMP=$(date -u +%Y%m%dT%H%M%SZ)
DEST=/var/backups/gisila-manual/$STAMP
mkdir -p "$DEST"
cp -a /etc/gisila/.env /etc/gisila/database.yaml /etc/gisila/secret.key "$DEST/"
# Use the connection details from /etc/gisila/database.yaml
PGPASSWORD='<db-password>' pg_dump -h 127.0.0.1 -U gisila -Fc gisila_panel > "$DEST/gisila_panel.dump"

Copy the result off the server.

2. Upgrade

upgrade.sh replaces only the panel’s own files: the four binaries, the web UI, the migrations, and the gisila-* systemd units if they changed. Then it runs the migrations and restarts gisila-panel and gisila-worker. Hosted apps keep running. It doesn’t touch apt packages, Nginx, TLS, /etc/gisila, Postgres, Redis or the firewall.

curl -fsSL https://raw.githubusercontent.com/gumisofts/gisila_panel/main/infra/upgrade.sh | sudo bash

# a specific release
curl -fsSL https://raw.githubusercontent.com/gumisofts/gisila_panel/main/infra/upgrade.sh \
  | sudo env VERSION=x.y.z bash

Before changing anything it saves the current files and a pg_dump of the panel database in /var/backups/gisila/<time>-<old version>/, keeping the newest three. If the migrations fail or the new version doesn’t answer within 30 seconds, it puts the old version back by itself.

Option	Effect
`VERSION=x.y.z`	Release to install (default `latest`).
`RELEASE_FILE=/path/to.tar.gz`	Install a local release tarball.
`FORCE=1`	Reinstall even if already on that version.
`SKIP_DB_BACKUP=1`	Skip the `pg_dump`, when you back up yourself or the local `pg_dump` is older than the server.
`ROLLBACK=1`	Restore files from the newest backup (or `BACKUP=<dir>`).

3. Roll an upgrade back

curl -fsSL https://raw.githubusercontent.com/gumisofts/gisila_panel/main/infra/upgrade.sh \
  | sudo env ROLLBACK=1 bash

This restores files, not the database. The old version then runs on the newer schema, which works because migrations only add. Restore the dump from /var/backups/gisila/… yourself if you need the old data.

4. Upgrade the agent separately (optional)

The agent is a separate binary that can be replaced on its own. GET /system/info reports the panel and agent versions side by side. A panel newer than its agent can pass flags the agent doesn’t know, so keep them in step. upgrade.sh updates both.

Uninstall

sudo bash infra/uninstall.sh          # panel services only; apps keep running
sudo bash infra/uninstall.sh --apps   # also removes every app and /srv/apps
sudo bash infra/uninstall.sh --purge  # also drops the panel DB/role (same host) and gisila:* Redis keys
sudo bash infra/uninstall.sh --all    # both

Verify it works

sudo systemctl status gisila-panel gisila-worker
curl -s https://panel.example.com/system/info -H 'Authorization: Bearer gsl_xxxxxxxxxxxxxxxx' \
  | jq .version