Deployment & Setup

This guide walks you through the complete deployment process for ApiFort, from extracting packages to starting the application.

graph TD
    A[Download Package] --> B[Step 1: Extract Package]
    B --> C[Step 2: Load Docker Images]
    C --> D[Step 3: Configure Hostname]
    D --> E[Step 4: Deploy Application]
    E --> F[Verification]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style E fill:#bfb,stroke:#333,stroke-width:2px

Step 1: Extracting Packages

You will receive a .tar.gz package, such as apifort-1.6.3.tar.gz.gpg. You will need the GPG password for decryption. The password will be provided by the ApiFort Team.

Follow these steps to decrypt and extract:

Decrypting the Package

Linux

Decrypt the package:

Bash

gpg --decrypt apifort-1.6.3.tar.gz.gpg > apifort.tar.gz

Extracting the Package

Linux

Extract the package:

Bash

mkdir apifort
tar -xvzf apifort.tar.gz -C apifort

After extraction, navigate to the apifort directory:

Bash

cd apifort

Step 2: Loading Docker Images

After extracting the tar.gz package, the Docker images need to be loaded into your system. These compressed Docker images are created using the docker save command, with compression reducing the package size by over 70%.

Performance Notes

• Estimated Time: The loading process typically takes 3–4 minutes, depending on your CPU performance.

Warning: If the process takes longer than 5 minutes, it may indicate that your CPU does not meet the minimum performance requirements.

Loading Images

To load the Docker images, use the provided configuration script:

Run the Loader Script

Linux

Bash

cd apifort
./config.sh load_images

This script will automatically:

• Check if Docker is installed and running
• Verify Docker permissions
• Load all .tar and .tar.gz files from the ./packages directory

Verifying Loaded Images

To verify the imported images:

Verification Command

Linux

Bash

docker image ls

Step 3: Hostname Configuration

Before deploying the application, you need to configure the hostname and generate SSL certificates. This is a critical step for proper operation.

Automated Configuration (Recommended)

The easiest way to configure the hostname, generate certificates, and update the environment variables is using the provided configuration script:

Bash

./config.sh set_hostname

This script will:

1. Prompt for your hostname (e.g., https://apifort.example.com)
2. Update docker-compose.yml with the correct environment variables:
   • KC_HOSTNAME (Keycloak hostname)
   • PUBLIC_HOST (Backend API URL)
   • ALLOWED_HOSTS (Allowed hostnames)
   • Keycloak__Url (Identigro Keycloak URL)
3. Generate self-signed certificates for the router in the ./tls directory
4. Configure Keycloak 26 specific settings

User Friendly Input

The script provides line editing support, so you can easily correct typos when entering the hostname.

What the Script Configures

The set_hostname script automatically configures these critical parameters:

Service	Parameter	Value Template
Backend	PUBLIC_HOST	https://yourdomain.com/api
Backend	ALLOWED_HOSTS	localhost:9050,yourdomain.com
Identigro	Keycloak__Url	https://yourdomain.com/auth
Keycloak	KC_HOSTNAME	https://yourdomain.com/auth
Router	TLS Certificates	Generated in ./tls/ directory

Manual Configuration

For manual configuration details, see the Configuration page.

Step 4: Deploy the Application

After configuration is complete, start the application using Docker Compose:

Start Concepts

Linux

Bash

cd apifort
docker compose up -d

The -d flag runs the containers in detached mode (background).

Your application is now starting! Continue to the monitoring section to verify deployment.

Monitoring Containers

After executing the docker compose up -d command, it is essential to monitor the status of your containers.

Checking Container Status

To view the status of all containers:

Check Status

Linux

Bash

docker compose ps

This command displays a list of all containers along with their current status (e.g., "Up", "Exited"). Look for any containers that are not in the "Up" state.

Viewing Logs

If a container is not running as expected or has exited, inspect its logs to identify the root cause:

Inspect Logs

Linux

Bash

docker compose logs <service-name>

Replace <service-name> with the name of the service (e.g., backend, keycloak, kafka).

Real-Time Log Monitoring

To monitor logs in real-time for all containers:

Follow Logs

Linux

Bash

docker compose logs -f

The -f flag allows you to follow the logs as they are being generated.

Service-Specific Log Monitoring

Monitor specific critical services:

Backend LogsKafka LogsDatabase Logs

Bash

docker compose logs -f backend

Bash

docker compose logs -f kafka

Bash

docker compose logs -f postgresql

Health Check Commands

Verify that critical services are responding correctly:

BackendKeycloakDatabase

Bash

curl -f http://localhost:9050/api/actuator/health
# or with your domain
curl -f http://your-domain.com:9050/api/actuator/health

Bash

curl -f http://localhost:8080/auth/health/ready

Bash

docker exec -it postgresql psql -U appuser -tAc 'select 1' -d apifort

Step 5: Access the Application

Once verifying the deployment, you can access the ApiFort UI using the hostname you configured during Step 3.

1. Open your web browser.
2. Navigate to the URL you set (e.g., https://apifort.example.com).
3. You will be redirected to the login page.

Default Credentials

If this is your first time logging in, refer to the Logging In guide for default credentials and initial setup instructions.

Stopping and Restarting Containers

If you need to stop and restart the containers:

Stop & Restart Operations

Stopping ContainersRestarting ContainersRestart Specific Service

Linux

Bash

docker compose down

Linux

Bash

docker compose up -d

Bash

docker compose restart <service-name>

Additional Commands

Resource Monitoring

Bash

# View resource usage for all containers
docker stats

# View resource usage for specific container
docker stats <container_name>

# View system resource usage
df -h  # Disk usage
free -h  # Memory usage
top  # CPU usage

Container Inspection

Bash

# Inspect container details
docker inspect <container_name>

# Execute commands inside container
docker exec -it <container_name> /bin/bash

# View container processes
docker exec -it <container_name> ps aux

Network Troubleshooting

Bash

# List Docker networks
docker network ls

# Inspect network details
docker network inspect apifort-network

# Test connectivity between containers
docker exec -it backend ping postgresql
docker exec -it backend ping kafka

Best Practices for Monitoring

Regular Monitoring Tasks

• Daily: Check container status using docker compose ps
• Weekly: Review container logs for errors or warnings
• Monthly: Monitor resource usage trends and optimize if necessary

Automated Monitoring

• Set up log rotation to prevent disk space issues
• Configure alerts for container failures
• Monitor resource usage thresholds
• Implement health check endpoints monitoring

Security Considerations

• Regularly update container images
• Monitor access logs for suspicious activity
• Ensure proper firewall configuration
• Use strong passwords and rotate them regularly

Performance Optimization

• Monitor response times and optimize slow queries
• Adjust container resource limits based on usage patterns
• Implement caching strategies where appropriate
• Regular database maintenance and optimization

Quick Reference Commands

Bash

# Essential monitoring commands
docker compose ps                    # Check container status
docker compose logs -f              # Follow all logs
docker compose logs <service>       # View specific service logs
docker stats                        # Monitor resource usage
docker compose restart <service>    # Restart specific service
docker compose down && docker compose up -d  # Full restart

# Troubleshooting commands
docker compose config               # Validate configuration
docker exec -it <container> bash    # Access container shell
docker inspect <container>          # Detailed container info
netstat -tulpn | grep <port>       # Check port usage (Linux)

Next Steps

After deployment is complete:

1. Configure advanced settings - For manual configuration and HTTPS setup
2. Set up monitoring - Configure Prometheus and Grafana
3. Activate your license - Apply your ApiFort license key
4. Check troubleshooting guide - If you encounter any issues

Deployment Complete!

Your ApiFort instance is now running. Access the application at the hostname you configured.