Configuration¶

This page provides detailed manual configuration instructions for ApiFort.

Manual Configuration¶

If you prefer to configure manually instead of using the ./config.sh set_hostname script, follow these steps.

Required Configuration Parameters¶

You need to update several environment variables in the docker-compose.yml file located in your apifort directory.

Backend Service Settings¶

Update environment variables in the backend service:

ALLOWED_HOSTS: apifort.yourdomain.com,localhost:9050
PUBLIC_HOST: https://apifort.yourdomain.com/api

Kafka Service Settings¶

Update kafka service:

KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:9092,EXTERNAL://<YOUR_IP>:9094

Replace <YOUR_IP> with your server's public IP address.

Identigro Service Settings¶

Update identigro service. Note that Keycloak__Url should point to the auth endpoint:

YAML

identigro:
  environment:
    Keycloak__Url: https://apifort.yourdomain.com/auth

Keycloak Service Settings (Keycloak 26+)¶

For Keycloak 26, KC_HOSTNAME must be the full URL (including schema and path) when KC_HOSTNAME_BACKCHANNEL_DYNAMIC is enabled:

YAML

keycloak:
  environment:
    # Full URL including /auth is required
    KC_HOSTNAME: https://apifort.yourdomain.com/auth
    KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true"
    KC_PROXY_HEADERS: "xforwarded"

Configuration Examples¶

Complete Example¶

docker-compose.yml

# Backend service configuration
backend:
  environment:
    ALLOWED_HOSTS: apifort.example.com,localhost:9050
    PUBLIC_HOST: https://apifort.example.com/api

# Identigro
identigro:
  environment:
    Keycloak__Url: https://apifort.example.com/auth

# Kafka
kafka:
  environment:
    KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:9092,EXTERNAL://203.0.113.10:9094

# Keycloak (v26)
keycloak:
  environment:
    KC_HOSTNAME: https://apifort.example.com/auth
    KC_HOSTNAME_BACKCHANNEL_DYNAMIC: "true"
    KC_PROXY_HEADERS: "xforwarded"

Verification Commands¶

After updating the configuration, verify your settings:

Verification

Check Current IPTest Kafka Connectivity

Bash

# Get your public IP
curl ifconfig.me

# Get your internal IP
hostname -I

Bash

# Test Kafka external listener
docker exec -it kafka /opt/kafka/bin/kafka-topics.sh --list --bootstrap-server YOUR_PUBLIC_IP:9094

Important

Remember to replace placeholder values (like your-domain.com, 203.0.113.10) with your actual server information.

HTTPS Configuration¶

Enabling HTTPS in Router¶

The application uses Nginx as a router for handling HTTP/HTTPS requests. By default, the application runs on HTTP. To enable HTTPS, you need to modify the Nginx configuration.

Automated Certificate Generation

The ./config.sh set_hostname script automatically generates self-signed certificates. If you used that script, you can skip manual certificate generation.

Prerequisites¶

DNS A Records: Properly configured DNS A records pointing to your server's IP address.
SSL Certificates: To enable HTTPS, you need:
- A valid SSL certificate (.crt file)
- The corresponding SSL certificate key (.key file)

Nginx Configuration Directory¶

The Nginx configuration files are located in the router directory under the application's installation path. This directory is mounted into the Nginx container using the Docker Compose configuration.

Example Nginx Configuration for HTTPS¶

Below is an example of the relevant part of the Nginx configuration file. To enable HTTPS, uncomment the necessary lines and comment out the HTTP lines:

router/default.conf

### UNCOMMENT THE LINES BELOW TO CONVERT APPLICATION TO HTTPS

# Redirect all HTTP traffic to HTTPS
#server {
#    listen 80;
#    # Redirect HTTP to HTTPS
#    return 301 https://$server_name$request_uri;
#}

server {
    listen 80 default_server; # COMMENT THIS LINE IF ENABLING HTTPS
#   listen 443 ssl default_server; # UNCOMMENT THIS LINE TO ENABLE HTTPS

#   ssl_certificate /etc/nginx/conf.d/test_netfein.crt; # UNCOMMENT THIS LINE TO SPECIFY SSL CERTIFICATE
#   ssl_certificate_key /etc/nginx/conf.d/test_netfein.key; # UNCOMMENT THIS LINE TO SPECIFY SSL KEY
}

Steps to Enable HTTPS¶

1. Obtain SSL Certificates

You need a valid SSL certificate (.crt) and a private key (.key) file.
Place these files in the router directory (e.g., router/your_cert.crt and router/your_cert.key).

Certificate Name Match

You must update the certificate lines according to your certificate names in the config file.

2. Modify the Nginx Configuration

Open the Nginx configuration file in the router directory.
Uncomment the lines for HTTPS:
- listen 443 ssl default_server;
- ssl_certificate and ssl_certificate_key.
Comment out the line for HTTP: listen 80 default_server;.

3. Enable HTTP to HTTPS Redirection (Optional)

Uncomment the block that redirects HTTP traffic to HTTPS:

Nginx Configuration File

server {
    listen 80;
    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

4. Restart the Router Container

Restart the Router container to apply the changes:
Bash
```
docker compose restart router
```

Example Workflow¶

Update the Nginx configuration to enable HTTPS:
- Place the SSL certificate and key in the router directory.
- Modify the Nginx configuration file as described above.
Restart the Router service:
Bash
```
docker compose restart router
```
Keycloak Update

You must also update Keycloak settings in docker-compose.yml to use HTTPS URLs.
Verify that the application is accessible via HTTPS.

Notes¶

Certificate Validity: Ensure that the SSL certificate is valid and trusted by the browser to avoid security warnings.
Backup Configuration Files: Before making changes to the Nginx configuration, create a backup of the original file.
:material-firewall: Firewall Settings: Ensure that ports 80 and 443 (for HTTPS) are open in your firewall.

Advanced Configuration¶

Environment File (.env)¶

Some advanced configuration options can be set via environment variables. If you need to modify these:

Update the .env file in the apifort directory
Apply changes by restarting the containers:
Bash
```
docker compose up -d
```

Restart Required

Environment variable changes in .env are not applied automatically. You must restart the containers to apply changes.

Docker Compose Validation¶

Before applying configuration changes, validate your docker-compose.yml syntax:

Bash

docker compose config

This command will show any syntax errors in your configuration file.