Deployment runbook
Services, releases and checks
The deployed platform is a group of independent Git repositories and systemd services behind Nginx. Deploy one component at a time and verify its integration boundaries.
Current services
| Service | Directory or executable | Bind |
|---|---|---|
| Mivama Portal | /home/frappe/mivama-portal | 127.0.0.1:3110 |
| Frappe web | /home/frappe/frappe/frappe-bench | 127.0.0.1:8011 |
| Frappe Socket.IO | bench runtime | 127.0.0.1:9001 |
| AI Studio web | /home/frappe/websitebuilder.wiaryle.com | 127.0.0.1:3200 |
| Hosting runner | /opt/mivama/runner/mivama_runner.py | outbound pull |
| Migration gateway | mivama-migration-gateway.service | narrow runtime endpoint |
| Migration worker | mivama-migration-worker.service | outbound pull/local host |
| Studio worker | /opt/mivama/studio-worker | local host and outbound |
| Documentation | /var/www/docs.wiaryle.com | 127.0.0.1:3120 |
| Mivama UI Storybook | /var/www/mivama-ui → /var/www/mivama-ui-storybook/current | Static Nginx route /ui/ |
Portal deploy
- Inspect Git status and preserve unrelated changes.
- Pull or apply the intended commit.
- Install dependency changes when package lock changed.
- Run the production Next build.
- Restart mivama-portal.service.
- Verify service log, loopback health and public login/API.
Mivama Core deploy
- Inspect app changes, especially DocType JSON, patches and hooks.
- Back up the Frappe site when schema/accounting behavior changes.
- Run bench migrate for the correct site.
- Build assets only when required.
- Restart/reload bench processes.
- Confirm scheduler and workers can import the updated methods.
- Exercise a read-only Portal call and inspect errors.
Runner/Ansible changes also require installing the reviewed runner/playbook release under /opt/mivama with correct permissions, then restarting its systemd service. Source commit and installed runtime must match.
Studio deploy
Build the monorepo according to its package scripts, migrate the Studio database if the schema changed, deploy both web and worker code, then restart web and privileged worker. Verify Core shared-secret calls, one launch redemption and a read-only workspace status.
Nginx and TLS
Application upstreams bind to loopback. Nginx owns public TLS, Host and forwarding headers, request size/timeouts appropriate to each surface. Always run nginx -t before reload. Certificates are issued/renewed by Certbot; the HTTP challenge path must remain reachable.
The /ui/ location is not a Next.js instruction page. It aliases the current atomic Storybook release built from the complete mivama-digital/mivama-ui checkout. mivama-ui-docs-sync.timer checks origin/main every five minutes. When the commit changes, its oneshot service performs locked dependency installation and Storybook build in a temporary release directory, verifies index.html and iframe.html, then atomically switches current. A failed build leaves the previous release online.
Release verification
Use a small proportional check:
- systemd unit is active and not restart-looping;
- loopback endpoint responds;
- public hostname serves the expected certificate and status;
- one main navigation route renders;
- application journal has no new fatal exception.
Do not run destructive migration/provisioning flows as a deployment smoke test.