Hivel On-Premises Deployment Guide (Generic)
Complete step-by-step guide for deploying Hivel services on prem.
Important:
All registry credentials, database passwords, and application passwords in this guide are placeholders. Generate your own credentials using openssl rand -base64 24 and store them in a secrets manager. Never reuse example credentials in production.
Review the host-Docker architecture (API Gateway, Services, integration connectors, self-managed PostgreSQL) and confirm on-premises deployment is the right choice for your environment.
Verify host sizing specifications, confirm open ports, and install Docker, Docker Compose, and AWS CLI on the host.
Confirm all prerequisites: required servers, license files, registry/S3 access credentials, compatible software versions, and full inbound/outbound network access per requirements.
Install PostgreSQL, set the superuser password, open database access from the host, and create the insightly application database.
Download the hivel-onprem package from S3 to the host and add license files to the project directory.
Configure AWS CLI credentials on both hosts and authenticate to Hivel's ECR image registry (or optional private registry mirror).
Create and configure the .env file with superuser credentials (for initial setup) and application-user credentials (for runtime), applying correct password-quoting rules.
Run the Flyway migration on the host to initialize the schema and create the application database user.
Deploy services using ./deploy.sh (recommended). This handles image pulls, startup ordering, health checks, and logging; see command reference for options.
Deploy services using ./deploy.sh --vm or ./deploy.sh --service (recommended). This handles image pulls, startup ordering, health checks, and logging; see full command reference for all available options.
Deploy services using ./deploy.sh --vm or ./deploy.sh --service (recommended). This handles image pulls, startup ordering, health checks, and logging; see full command reference for all available options. Alternatively, manually create the shared Docker network and run docker-compose per host/service for finer-grained control.
Set up daily log rotation with 7-day retention across all containers.
Verify installation is complete: confirm all services pass health checks, complete the validation checklist, and confirm UI access via direct IP, your reverse proxy, or Caddy.
Complete initial application setup: create user account, configure organization, and integrate essential external tools.
ADVANCED
Set up Caddy reverse proxy for automatic HTTPS via Let's Encrypt or self-signed certificate, including management and troubleshooting.
Reference file locations for config, license, Docker Compose, and log files.
Troubleshoot deployment issues using symptom-cause-diagnostic-resolution guide for service startup, database connection, registry pull, migration, credentials, ports, health checks, and log rotation.
Back up and restore the insightly database using pg_dump/pg_restore, including post-restore permissions re-evaluation.
Upgrade to new image versions or roll back; note that Flyway migrations are not easily reversible.
Uninstall and clean up: back up data, stop/remove services, decommission hosts, clean infrastructure, and revoke all credentials.
Secure credentials and rotate database passwords using least-privilege roles (superuser vs. application-user).
Before Contacting Support,
collect required information: status/health output, container logs, redacted .env file, software versions, and timestamps.
Complete the deployment checklist confirming all steps above before moving to Integration Setup.
Last updated