Push-to-Deploy Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Push-to-Deploy workflow automates the deployment of Nyansa from a local development machine to a production server. It uses Git hooks and shell scripts to build immutable releases, perform backups, and ensure service health before finalizing updates. This process prevents partial deployments and provides an automatic rollback mechanism if a new release fails to start.
Sources: README.md:46-51, README.md:126-133
Deployment Lifecycle
The deployment process triggers when you execute a git push prod main command. It involves two distinct phases: pre-push validation on the developer machine and post-receive deployment on the server.
Phase 1: Local Validation
Before the code leaves the developer machine, a pre-push hook executes the following:
- Secrets Scanning: The script scans the commit for tracked secrets or environment files to prevent accidental leakage.
- Release Building: It creates a self-contained release folder using
git archive. This ensures that only committed files are included in the deployment. - Validation: It runs
docker compose configand exposure checks against the release folder using.env.example.
Sources: README.md:127-128, scripts/build-publish.sh:4-8
Phase 2: Server-Side Execution
Once the server receives the push, the post-receive hook performs these actions:
- Release Extraction: Builds a release directory at
/opt/nyansa/releases/<sha>/. - Environment Linking: Links the production
.envfile to the new release folder. - State Protection: Executes
scripts/backup.shto take a logical dump of the PostgreSQL database and archive stateful volumes. - Stack Initialization: Pulls Docker images and starts the stack.
Sources: README.md:129-130, scripts/backup.sh:4-9
Deployment Flow Diagram
The following diagram illustrates the sequence of operations from the local push to the final server health check.
Release Engineering
Releases are designed to be immutable and self-contained. The scripts/build-publish.sh script defines which files are necessary for the runtime environment, excluding development-only assets like documentation and tests.
Runtime Components
The deployment includes a specific set of paths required for the Docker stack to function:
- Core Config:
docker-compose.ymland thecaddy/directory. - Workflows: The
n8n/directory containing demo-data and workflows. - Service Logic: The
srcand build configurations formemory-api. - Maintenance Scripts:
lib.sh,backup.sh,restore.sh, andwait-healthy.sh.
Sources: scripts/build-publish.sh:26-44
Release Identification
Each release generates a RELEASE file containing metadata:
- The full and short Git SHA.
- The branch name.
- Commit and build timestamps.
Additionally, the script injects the short SHA into the docker-compose.yml image tags. This ensures that the nyansa-memory-api service runs the specific image built from that release's source code.
Sources: scripts/build-publish.sh:78-83, scripts/build-publish.sh:91-98
Reliability and Rollback
Nyansa prioritizes system availability by validating container health before committing to a new release.
Health Monitoring
The scripts/wait-healthy.sh script monitors the stack until every container reaches a "healthy" state. If a container enters a crash loop, the script detects this after 3 restarts without waiting for the full timeout.
Sources: README.md:132, scripts/wait-healthy.sh
Automatic Rollback
A deployment is only considered successful when the /opt/nyansa/current symlink is updated to point to the new release. If the health check fails:
- The
currentsymlink remains unchanged, pointing to the previous working version. - The system restarts the containers associated with the previous release.
- The failed release folder is discarded.
Sources: README.md:132-133
Backup Procedures
The scripts/backup.sh utility is a critical part of the deployment workflow, creating a restorable state of the system before changes are applied.
Backup Summary
| Component | Method | Target |
|---|---|---|
| PostgreSQL | pg_dump | postgres.dump |
| n8n State | tar archive | nyansa_n8n_storage.tar.gz |
| Vector Store | tar archive | nyansa_qdrant_storage.tar.gz |
| Proxy Data | tar archive | nyansa_caddy_data.tar.gz |
| Tailscale | tar archive | nyansa_tailscale_state.tar.gz |
Sources: scripts/backup.sh:31-48
To ensure data consistency in SQLite files (Open WebUI) and Qdrant segments, the script stops the writer containers (like nyansa-n8n, nyansa-qdrant, and nyansa-open-webui) before archiving volumes, then restarts them immediately after.
Sources: scripts/backup.sh:10-14, scripts/backup.sh:100-112
Summary
The Push-to-Deploy workflow enables a safe, reproducible path for deploying the Nyansa stack. By combining Git-based versioning with mandatory pre-deployment backups and post-deployment health checks, the system ensures that production environments can be updated with minimal risk and high traceability.
Sources: README.md:46-51, scripts/build-publish.sh:4-8