Automated Installation

The fastest way to deploy Hawkra Self-Hosted is with the automated install script. A single command handles prerequisites, configuration, and startup.

Prerequisites

Before running the script, ensure your server meets the system requirements:

• Linux server with root or sudo access
• 2+ CPU cores, 4 GB+ RAM, 48 GB+ disk space
• Ports 80 and 443 available (not in use by another service)
• curl installed

Run the Installer

As root:

curl -sSL https://hawkra.io/self-install.sh | bash

As a sudo user:

curl -sSL https://hawkra.io/self-install.sh | sudo bash

Security Best Practice

Always review scripts before piping them to your shell. Download and inspect the script first:

curl -sSL https://hawkra.io/self-install.sh -o self-install.sh
less self-install.sh
# As root:
bash self-install.sh
# Or as a sudo user:
sudo bash self-install.sh

What the Script Does

1. System prerequisite checks -- verifies supported Linux distro, x86_64 architecture, 48 GB disk, required tools (curl, openssl), and ports 80/443 availability. Exits on failure.
2. Docker installation -- installs Docker Engine and Compose from the official repository if not already present (24.0+ required).
3. Directory structure -- creates /opt/hawkra/ with subdirectories for Caddy, certificates, and license files.
4. Configuration file download -- downloads docker-compose.selfhosted.yml, Caddyfile, and caddy/docker-entrypoint.sh from the distribution server.
5. Domain configuration -- prompts for your domain name, hostname, or IP address.
6. Secret generation -- generates all required secrets (DB password, JWT secret, master encryption key) using openssl.
7. Environment file -- writes secrets and domain configuration to /opt/hawkra/.env with chmod 600.
8. Service startup -- pulls container images and starts all five services with docker compose up -d.
9. Health check -- waits for PostgreSQL, Redis, backend, frontend, and Caddy to report healthy. Shows container logs on failure.
10. Admin credentials -- displays the initial admin email (admin@hawkra.local) and randomly generated password.

danger

The admin password is displayed only during initial installation. Save it immediately. Losing it requires a full reset (destroys all data).

Post-Installation Steps

1. Open https://your-domain (or https://your-ip) in a browser. Accept the certificate warning if using self-signed certs.
2. Log in with admin@hawkra.local and the password from the installer output.
3. Change the default admin password in Account Settings.
4. Upload your license file on the License Setup page. See Licensing for details.
5. Optionally configure AI Assistant, SMTP, and OSINT API Keys under Admin > Settings.

Admin Page Access

Only the initial admin account (admin@hawkra.local) can access the /admin page. Navigate to it manually by appending /admin to your domain URL (e.g., https://your-domain/admin) -- there is no direct link to it within the application.

Installation Directory Reference

After installation, the following directory structure exists at /opt/hawkra/:

/opt/hawkra/
  .env                              # Environment configuration (chmod 600)
  docker-compose.selfhosted.yml     # Docker Compose service definitions
  Caddyfile                         # Caddy reverse proxy template
  caddy/
    docker-entrypoint.sh            # Caddy startup and TLS configuration
  certs/                            # Custom TLS certificates (optional)
  license/                          # License file directory

Managing the Installation

All commands run from /opt/hawkra:

# Status
docker compose -f docker-compose.selfhosted.yml ps

# Logs (all services, or replace with specific service name)
docker compose -f docker-compose.selfhosted.yml logs -f [backend|frontend|caddy|postgres|redis]

# Restart
docker compose -f docker-compose.selfhosted.yml restart

# Stop
docker compose -f docker-compose.selfhosted.yml down

# Start
docker compose -f docker-compose.selfhosted.yml up -d

Troubleshooting

If the installer fails or services do not start correctly, check the following:

Issue	Solution
Script fails on prerequisite check	Verify your server meets the system requirements
Docker installation fails	Install Docker manually following Docker's official guide and re-run the script
Port 80 or 443 already in use	Stop the conflicting service (e.g., sudo systemctl stop nginx apache2) before running the installer
Services fail health check	Run docker compose -f docker-compose.selfhosted.yml logs to identify the failing service
Browser shows "connection refused"	Wait 30-60 seconds for services to fully initialize, then check docker compose ps
Certificate warning in browser	Expected with self-signed certificates -- accept the warning to proceed

For detailed troubleshooting steps, see the Manual Installation troubleshooting section.