Skip to main content

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
  • 4+ CPU cores, 8 GB+ RAM, 50 GB+ disk space
  • Ports 80 and 443 available (not in use by another service)
  • curl installed

Run the Installer​

curl -sSL https://hawkra.io/self-install.sh | 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
bash self-install.sh

What the Script Does​

The installer performs the following steps in order:

1. System Prerequisite Checks​

The script verifies:

  • Operating system is a supported Linux distribution
  • CPU architecture is x86_64 (amd64)
  • Available disk space meets the 50 GB minimum
  • Required tools (curl, openssl) are present
  • Ports 80 and 443 are not already in use

If any check fails, the script displays an error message and exits without making changes.

2. Docker Installation​

If Docker Engine and Docker Compose are not already installed, the script installs them using the official Docker repository for your distribution. If Docker is already present and meets the minimum version requirement (24.0+), this step is skipped.

3. Directory Structure​

The script creates the Hawkra installation directory:

/opt/hawkra/
  docker-compose.selfhosted.yml
  Caddyfile
  .env
  caddy/
    docker-entrypoint.sh
  certs/
  license/

4. Configuration File Download​

The following files are downloaded from the Hawkra distribution server:

  • docker-compose.selfhosted.yml -- Docker Compose service definitions
  • Caddyfile -- Caddy reverse proxy configuration template
  • caddy/docker-entrypoint.sh -- Caddy startup script that handles TLS mode selection

5. Domain Configuration​

The script prompts you for your domain name:

Enter the domain or IP address for this Hawkra instance:
> hawkra.yourcompany.com

You can enter:

  • A fully qualified domain name (e.g., hawkra.yourcompany.com) -- recommended for automatic Let's Encrypt TLS
  • A hostname (e.g., hawkra.local) -- works with self-signed certificates
  • An IP address (e.g., 192.168.1.100) -- works with self-signed certificates

6. Secret Generation​

The script generates all required secrets automatically using openssl:

SecretGeneration MethodPurpose
POSTGRES_PASSWORDopenssl rand -base64 24PostgreSQL database password
JWT_SECRETopenssl rand -hex 32JWT token signing key
MASTER_ENCRYPTION_KEYopenssl rand -hex 32Master key for encrypting per-workspace data encryption keys
tip

The script generates all secrets automatically. You do not need to create passwords or encryption keys manually.

7. Environment File Configuration​

The generated secrets and your domain are written to /opt/hawkra/.env. The file is created with restrictive permissions (chmod 600) so only root can read it. The environment file includes:

  • Database credentials
  • JWT signing configuration
  • Encryption keys
  • Domain and URL settings
  • CORS configuration
  • Cookie settings

8. Service Startup​

The script pulls the container images and starts all five services:

docker compose -f docker-compose.selfhosted.yml pull
docker compose -f docker-compose.selfhosted.yml up -d

9. Health Check​

The script waits for each service to report healthy:

  1. PostgreSQL accepts connections (pg_isready)
  2. Redis responds to PING
  3. Backend starts listening on port 3001
  4. Frontend starts listening on port 3000
  5. Caddy begins serving on ports 80 and 443

If any service fails to become healthy within the timeout period, the script displays diagnostic information from the container logs.

10. Admin Credentials​

Once all services are healthy, the script extracts and displays the initial admin credentials from the backend logs:

============================================
  Hawkra is ready!

  URL:      https://hawkra.yourcompany.com
  Email:    admin@hawkra.local
  Password: <randomly-generated-password>

  Save this password -- it is only shown once.
============================================
danger

The admin password is displayed only during the initial installation. Write it down immediately. If you lose it before changing it, you will need to perform a full reset (which destroys all data) to generate a new one.

Post-Installation Steps​

1. Access the Platform​

Open your browser and navigate to:

  • https://your-domain if you provided a domain name
  • https://your-ip if you provided an IP address

If using self-signed certificates (the default when no domain points to the server), your browser will display a certificate warning. Accept the warning to proceed.

2. Log In​

Sign in with the admin credentials displayed by the installer:

  • Email: admin@hawkra.local
  • Password: the password shown in the terminal output

3. Change the Admin Password​

Navigate to Account Settings and change the default admin password immediately.

4. Upload Your License​

After logging in, you will be redirected to the License Setup page. Upload the license file provided with your purchase to activate the platform.

info

If you do not have a license yet, see License & Billing FAQ for information about purchasing one.

5. Configure Optional Features​

After activation, you can optionally configure:

  • AI Assistant -- Set up a Gemini API key or connect a local LLM server through Admin > Settings > AI Configuration
  • SMTP -- Enable email verification and password resets through Admin > Settings > Email (SMTP)
  • OSINT API Keys -- Add Shodan, HIBP, and GeoIP keys through Admin > Settings for enhanced reconnaissance

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​

View Service Status​

cd /opt/hawkra
docker compose -f docker-compose.selfhosted.yml ps

View Logs​

# All services
docker compose -f docker-compose.selfhosted.yml logs -f

# Specific service
docker compose -f docker-compose.selfhosted.yml logs -f backend

Restart Services​

cd /opt/hawkra
docker compose -f docker-compose.selfhosted.yml restart

Stop Services​

cd /opt/hawkra
docker compose -f docker-compose.selfhosted.yml down

Start Services​

cd /opt/hawkra
docker compose -f docker-compose.selfhosted.yml up -d

Troubleshooting​

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

IssueSolution
Script fails on prerequisite checkVerify your server meets the system requirements
Docker installation failsInstall Docker manually following Docker's official guide and re-run the script
Port 80 or 443 already in useStop the conflicting service (e.g., sudo systemctl stop nginx apache2) before running the installer
Services fail health checkRun 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 browserExpected with self-signed certificates -- accept the warning to proceed

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