Prepare your Forge site
Use a private repository, PHP 8.5, PostgreSQL, and a Laravel site with public as its web root. Install a TLS certificate before connecting a remote agent. No live site is provisioned by the local scaffold.
Preserve .env and storage across deployments. Configure a restricted database account and keep PostgreSQL inaccessible from the public internet.
Production environment
APP_ENV=production
APP_DEBUG=false
APP_URL=https://YOUR_ORBIT_DOMAIN
ORBIT_REQUIRE_HTTPS=true
CACHE_STORE=database
SESSION_DRIVER=file
QUEUE_CONNECTION=sync
LOG_STACK=daily
LOG_LEVEL=warning
Set a unique production APP_KEY once and supply database credentials securely. For a proxy deployment, trust only known proxies and verify HTTPS detection. Set Nginx’s client_max_body_size to 64k.
Build each release
Retain Forge’s generated checkout or release-creation and activation steps. In the new release directory, before activation:
$FORGE_PHP $FORGE_COMPOSER install --no-dev --no-interaction --prefer-dist --optimize-autoloader
npm ci
npm run build
$FORGE_PHP artisan migrate --force --no-interaction
$FORGE_PHP artisan optimize
The asset build styles these documentation pages. Markdown is rendered by Laravel and ships with the application. Review migrations and take a backup before a release. Do not put workspace setup, key generation, seeding, or token issuance into the recurring deployment script.
No queue worker or scheduler is needed for the current synchronous CRM tools.
Verify the connection
Provision the workspace and first agent over SSH. Check /up, confirm unauthenticated MCP calls are rejected, and complete the Hermes reconnect test.
/up checks application liveness. It does not prove database recovery or business-data integrity. Monitor application failures and backup failures separately; MCP request IDs help correlate problems.
Back up and rehearse recovery
Configure encrypted, off-server daily PostgreSQL backups and retain at least 14 daily copies. Alert on failures. Forge’s built-in database backups require its Business plan; another host or database-provider backup may be appropriate.
Before depending on Orbit, restore a backup into a new isolated database and validate IDs, records, timestamps, and authenticated retrieval. Do not expose restored active credentials. The production backup setup and recovery rehearsal are still pending.
Roll back deliberately
Roll application code back to a compatible Forge release. A database rollback is a separate decision: the foundation migration’s down() drops business tables. Never use it as a routine code rollback.
For an incompatible migration, validate a restored backup in a new database before switching the application. Keep the pre-recovery database until the result is accepted. See the repository README for the recovery procedure and the current limitations.
Refer to Forge’s official deployment and backup documentation for the hosting controls.
Public docs and private instances
A public project domain can serve the landing page and /docs, while each self-hosted CRM uses its own application domain and credentials. Configure the MCP client with the private instance's /mcp/orbit endpoint, not the public documentation hostname.
Keep the public site deployment separate from private workspace data and secrets. If serving documentation from a Laravel deployment, restrict /mcp/* at the public site's server boundary; do not copy the private instance's database credentials into it. This repository currently provides the documentation pages and CRM service; the standalone public landing page and its deployment are planned.
Before an upgrade, back up the database, review migrations, and follow the current build and migration steps above. The tag-registry upgrade backfills existing associations. Rolling it back removes field definitions and the tag registry; prefer a forward fix once these are in use.
The PostgreSQL connection explicitly uses UTC, independently of the database host timezone. Activity and task due times are converted to UTC before persistence. Earlier installs that inherited a non-UTC database session timezone should review historical timestamps when upgrading; this change does not reinterpret or rewrite stored history.
Feature upgrade notes
Orbit 0.4 adds task claim history, current claim/outcome fields, and an activity redaction timestamp. Run the new migrations before activating the new application release. Claims expire by timestamp checks; no scheduler is needed. Update the Hermes allowlist and reload its MCP connection after upgrading.
Do not roll back these migrations once task attempts are in use: rollback removes claim history and completion references, and older code cannot safely handle in-progress tasks. Prefer a forward fix or a verified database restore. Dropping the redaction timestamp cannot recover removed content.
The administrator export and redaction guide describes data portability and maintenance. Export is not a replacement for tested backups.
The instance root (/) is a public Orbit welcome page with a link to that same instance’s /docs. The public Orbit website destination is marked coming soon and remains inactive. The welcome page reads no CRM data; use /up for application liveness checks.
Guided owner installation
After deploying and running migrations, set APP_URL to your instance's HTTPS origin and SESSION_SECURE_COOKIE=true. Keep ORBIT_REQUIRE_HTTPS=true. Before handing over the site, open a secure SSH terminal in the application directory and run:
php artisan orbit:install
Follow the workspace and owner prompts, review the details, then sign in using the URL shown. No mail provider or setup code is needed. An existing workspace is preserved. The command requires interactive input and must not run in recurring deployment scripts. Public visitors cannot create accounts even if they reach the site before installation is complete. See Your account & agents for installation and recovery.