Maintenance

The Maintenance category covers operational settings for maintaining your Hawkra instance, including maintenance mode, Nmap scanning tools, health monitoring, and backup strategies.

Maintenance Mode Settings

Maintenance Mode

Key	maintenance_mode
Type	Boolean (toggle)
Default	false
Encrypted	No

When enabled, the platform displays a maintenance notification to all users. Use this when performing planned upgrades, database migrations, or other operations that may temporarily affect availability.

Maintenance Message

Key	maintenance_message
Type	String
Default	Empty
Encrypted	No

A custom message displayed to users when maintenance mode is active. Use this to communicate the reason for the maintenance window and an estimated time of completion.

Example: Scheduled maintenance in progress. Expected completion: 2:00 PM UTC.

Nmap License Management

The admin settings page includes a Scanning section (visible on self-hosted instances) for managing Nmap, the network port scanner used for network discovery and service detection.

Installing Nmap

Nmap is not installed by default. To enable network scanning:

1. Navigate to Admin > Settings.
2. In the Scanning section at the top of the page, click Install Nmap.
3. A dialog appears explaining that Nmap is licensed under the Nmap Public Source License (NPSL). Review the license terms at nmap.org.
4. Click Install Now to proceed. Nmap is downloaded and installed from the operating system package repository directly into the container.
5. Once installed, the button changes to an Installed badge.

Nmap persists across container restarts — you only need to install it once. However, if the container image is rebuilt (e.g., during a Hawkra version upgrade), you may need to reinstall Nmap.

note

By clicking Install, you acknowledge that you have reviewed and agree to comply with the Nmap Public Source License terms. Hawkra does not bundle Nmap directly — it is installed on-demand from the OS package repository.

Health Checks and Monitoring

Viewing Service Health

Monitor the health of your Hawkra services using Docker's built-in logging:

# View all service logs
cd /opt/hawkra && docker compose logs

# View backend logs (most useful for troubleshooting)
cd /opt/hawkra && docker compose logs backend

# Follow logs in real time
cd /opt/hawkra && docker compose logs -f backend

# View logs for a specific time range
cd /opt/hawkra && docker compose logs --since 1h backend

Checking Container Status

# View the status of all containers
cd /opt/hawkra && docker compose ps

# Expected output shows all services as "running" with health status

A healthy deployment shows all services (backend, frontend, database, Redis) in the running state.

Common Log Messages

Log Message	Meaning
DynamicSettings loaded N non-empty values from app_settings	Settings loaded successfully at startup
SMTP not configured - email features disabled	No SMTP environment variables or dashboard settings found
License valid, expires in N days	License is active
License expired, grace period: N days remaining	License expired but within grace period

Monitoring Recommendations

For production deployments, consider setting up:

• Docker healthchecks — The Docker Compose file includes healthcheck definitions. Monitor these through your container orchestration platform.
• Log aggregation — Forward Docker logs to a centralized logging service (e.g., Loki, ELK stack, or a cloud logging provider) for long-term retention and alerting.
• Uptime monitoring — Use an external monitoring service to periodically check your Hawkra instance's availability.

Backup Recommendations

Regular backups are essential for disaster recovery. A complete Hawkra backup includes three components:

1. Database Volume

The PostgreSQL database contains all your workspace data, user accounts, vulnerabilities, assets, notes, and configuration settings.

# Create a database dump
cd /opt/hawkra && docker compose exec db pg_dump -U hawkra hawkra > backup_$(date +%Y%m%d_%H%M%S).sql

# Restore from a dump
cd /opt/hawkra && docker compose exec -T db psql -U hawkra hawkra < backup_20260303_120000.sql

caution

Stop write-heavy operations before taking a database backup to ensure consistency. For production environments, consider using PostgreSQL's continuous archiving (WAL archiving) for point-in-time recovery.

2. File Storage Volume

If using local storage (the default), uploaded files are stored in the file_storage Docker volume.

# Find the volume mount point
docker volume inspect hawkra_file_storage --format '{{ .Mountpoint }}'

# Back up the volume
sudo tar -czf file_storage_backup_$(date +%Y%m%d_%H%M%S).tar.gz -C $(docker volume inspect hawkra_file_storage --format '{{ .Mountpoint }}') .

If using S3 storage, your files are already stored externally. Ensure your S3 bucket has its own backup or versioning policy.

3. Environment Configuration

Back up your .env file, which contains critical secrets:

cp /opt/hawkra/.env /opt/hawkra/.env.backup_$(date +%Y%m%d)

danger

The .env file contains your MASTER_ENCRYPTION_KEY, JWT_SECRET, and database credentials. Without the master encryption key, encrypted data in the database cannot be decrypted. Store this backup securely and separately from the database backup.

Backup Schedule

Component	Recommended Frequency	Method
Database	Daily	pg_dump or WAL archiving
File storage	Daily or weekly	Volume tar or rsync
.env file	After any change	File copy to secure location

Automated Backup Script

Here is an example script that backs up all three components:

#!/bin/bash
BACKUP_DIR="/opt/hawkra/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
mkdir -p "$BACKUP_DIR"

# Database
cd /opt/hawkra && docker compose exec -T db pg_dump -U hawkra hawkra > "$BACKUP_DIR/db_$TIMESTAMP.sql"

# File storage
VOLUME_PATH=$(docker volume inspect hawkra_file_storage --format '{{ .Mountpoint }}')
sudo tar -czf "$BACKUP_DIR/files_$TIMESTAMP.tar.gz" -C "$VOLUME_PATH" .

# Environment file
cp /opt/hawkra/.env "$BACKUP_DIR/env_$TIMESTAMP"

# Cleanup backups older than 30 days
find "$BACKUP_DIR" -type f -mtime +30 -delete

echo "Backup completed: $TIMESTAMP"

Schedule this with cron to run daily:

# Edit crontab
crontab -e

# Add this line to run at 2:00 AM daily
0 2 * * * /opt/hawkra/backup.sh >> /var/log/hawkra-backup.log 2>&1

Configuration via Environment Variables

Setting	Environment Variable
Maintenance Mode	MAINTENANCE_MODE
Maintenance Message	MAINTENANCE_MESSAGE

tip

Before performing major maintenance (upgrades, database migrations), enable maintenance mode through the admin dashboard to inform users, then proceed with your maintenance tasks. Disable it when complete.