Skip to main content
Version: 2026 R1

Docker configuration

This section describes the docker-compose configuration included with the AI Proxy project, which allows you to run the service locally or in a development container. The Docker setup is particularly useful for:

  • local development without the full Azure infrastructure,
  • test environments,
  • Self-hosted deployments,
  • demos and prototyping.

Available Docker Compose variants​

In the scripts/docker/ directory, the following docker-compose variants are available:

  • docker-compose-basic-pem.yml - basic configuration using a PEM-formatted certificate,
  • docker-compose-basic-pfx.yml - basic configuration using a PFX-formatted certificate,
  • docker-compose-applicationinsights.yml - configuration with Application Insights integration for monitoring.

Service structure AI-proxy​

The main Docker service for AI Proxy includes the following elements:

Image

image: docker-dev.webcon.pl/webcon/aiproxy:<version_tag>

or for local builds:

image: localbuild

Container name

container_name: ai-proxy

Restart policy

restart: unless-stopped

The container automatically restarts on failure unless it has been stopped manually.

Port configuration​

ports:
  - "5298:8080"  # HTTP
  - "7033:8081"  # HTTPS
info
  • Host port 5298 is mapped to container port 8080 (HTTP).
  • Host port 7033 is mapped to container port 8081 (HTTPS).
  • Adjust the host ports if they conflict with other services on the machine.

Environment variables​

Docker Compose sets the following environment variables for the container:

Base variables​

environment:
  - ASPNETCORE_ENVIRONMENT=Production
  - AppConfiguration__SelfHosted__Certificate__Path=/app/https/certificate.pem
  - Logging__LogLevel__Default=Information
  - Logging__LogLevel__Microsoft=Warning

Variable descriptions:

  • ASPNETCORE_ENVIRONMENT - the ASP.NET Core environment (Development, Staging, Production),
  • AppConfiguration__SelfHosted__Certificate__Path - path to the TLS certificate inside the container,
  • Logging__LogLevel__Default- default log level,
  • Logging__LogLevel__Microsoft - log level for Microsoft namespaces.

Self-hosted mode variables​

To run in Self-hosted mode, add:

environment:
  - AppConfiguration__SelfHosted__Enabled=true
  - AppConfiguration__UseAzureKeyVault=false

Volumes​

Volumes mount files from the host into the container.

TLS certificate (PEM)

volumes:
  - ./certificates/certificate.pem:/app/https/certificate.pem:ro

TLS certificate (PFX)

volumes:
  - ./certificates/certificate.pfx:/app/https/certificate.pfx:ro
info
  • :ro means read-only.
  • Make sure the certificate file exists in ./certificates/ before starting the container.

AI configuration file

volumes:
  - ./aiconfiguration.json:/app/aiconfiguration.json:ro
info
  • When UseAzureKeyVault = true, the file must contain Key Vault secret names (NOT actual keys).
  • When UseAzureKeyVault = false, the file must contain all required secrets (only for local/test environments).

Sample Docker Compose configuration​

Variant with a PEM certificate​

version: '3.8'

services:
  ai-proxy:
	image: localbuild
	container_name: ai-proxy
	restart: unless-stopped
	ports:
	  - "5298:8080"
	  - "7033:8081"
	environment:
	  - ASPNETCORE_ENVIRONMENT=Development
	  - AppConfiguration__SelfHosted__Enabled=true
	  - AppConfiguration__SelfHosted__Certificate__Path=/app/https/certificate.pem
	  - AppConfiguration__UseAzureKeyVault=false
	  - Logging__LogLevel__Default=Information
	  - Logging__LogLevel__Microsoft=Warning
	volumes:
	  - ./certificates/certificate.pem:/app/https/certificate.pem:ro
	  - ./aiconfiguration.json:/app/aiconfiguration.json:ro

Variant with a PFX certificate​

version: '3.8'

services:
  ai-proxy:
	image: localbuild
	container_name: ai-proxy
	restart: unless-stopped
	ports:
	  - "5298:8080"
	  - "7033:8081"
	environment:
	  - ASPNETCORE_ENVIRONMENT=Development
	  - AppConfiguration__SelfHosted__Enabled=true
	  - AppConfiguration__SelfHosted__Certificate__Path=/app/https/certificate.pfx
	  - AppConfiguration__SelfHosted__Certificate__Password=YourCertificatePassword
	  - AppConfiguration__UseAzureKeyVault=false
	  - Logging__LogLevel__Default=Information
	volumes:
	  - ./certificates/certificate.pfx:/app/https/certificate.pfx:ro
	  - ./aiconfiguration.json:/app/aiconfiguration.json:ro

Running Docker Compose​

Environment preparation​

Before starting the container, make sure that:

  1. Docker Desktop (or Docker Engine) is running.
  2. The certificate files exist - ./certificates/certificate.pem or ./certificates/certificate.pfx.
  3. The AI configuration file ./aiconfiguration.json exists and contains a valid configuration (Key Vault secret names, or real values in offline mode).
  4. Ports 5298 and 7033 are available.

Starting from the repository​

From the root of the repository (where the scripts folder is located):

cd .\scripts\docker
docker-compose -f docker-compose-basic-pem.yml up -d

or for the PFX variant:

docker-compose -f docker-compose-basic-pfx.yml up -d

Viewing logs​

To stream logs in real time:

docker-compose logs -f ai-proxy

To view the most recent logs:

docker-compose logs --tail=100 ai-proxy

Stopping and removing containers​

docker-compose down

To also remove volumes:

docker-compose down -v

Generating test certificates​

For development environments, you can generate a self-signed certificate.

Generate a PEM certificate (Linux/macOS/PowerShell)​

# Generate a private key and certificate
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Combine into a single file
cat key.pem cert.pem > certificate.pem

# Move to the certificates directory
mv certificate.pem ./certificates/

Generate a PFX certificate (Windows/PowerShell)​

# Generate a certificate using PowerShell
$cert = New-SelfSignedCertificate -DnsName "localhost" -CertStoreLocation "cert:\CurrentUser\My" -NotAfter (Get-Date).AddYears(1)

# Export to PFX
$password = ConvertTo-SecureString -String "YourPassword123" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath ".\certificates\certificate.pfx" -Password $password

Docker troubleshooting​

Problem:
The container does not start

Symptoms:

  • the container stops immediately after startup,
  • no response on ports 5298/7033.

Resolution:

# Check the container logs
docker-compose logs ai-proxy

# Check the container status
docker ps -a

# Inspect the configuration
docker inspect ai-proxy

Common causes:

  • missing certificate file,
  • incorrect certificate path in the environment variable,
  • errors in the aiconfiguration.json file,
  • host ports are already in use.

Problem:
File access error

Symptoms:

  • errors indicating insufficient permissions to read files,
  • the container cannot load the certificate or configuration.

Resolution:

# Check file permissions
Get-Acl .\certificates\certificate.pem

# Check Docker Desktop settings
# Docker Desktop > Settings > Resources > File Sharing
# Add the project directory to the shared list

Problem: Ports already in use

Symptoms:

  • startup error: "port is already allocated".

Resolution:

# Find the process using the port
netstat -ano | findstr :7033

# Stop the process or change ports in docker-compose.yml
ports:
  - "5299:8080"  # Changed host port
  - "7034:8081"  # Changed host port

Problem:
SSL certificate errors

Symptoms:

  • SSL/TLS errors when attempting to connect,
  • the browser shows a certificate warning.

Resolution:

# Verify the certificate format
openssl x509 -in ./certificates/certificate.pem -text -noout

# Make sure the path in the environment variable is correct
# Check whether the container can see the file
docker exec ai-proxy ls -l /app/https/

Problem:
AI configuration errors

Symptoms:

  • the application starts but cannot connect to AI providers,
  • log errors indicating missing secrets.

Resolution:

# Check the configuration file contents
cat .\aiconfiguration.json

# Verify if:
# 1. UseAzureKeyVault=false in Self-hosted mode
# 2. All required secrets are present in the file
# 3. The JSON format is valid

# Restart the container after fixes
docker-compose restart ai-proxy

Pre-start checklist​

  • Docker Desktop/Engine is running.
  • The ./certificates/certificate.pem or .pfx file exists and is valid.
  • The ./aiconfiguration.json file exists and contains a valid configuration.
  • Secrets in the configuration match the runtime mode (UseAzureKeyVault=false for Self-hosted).
  • Ports 5298 and 7033 are free (or the mapping has been adjusted in docker-compose.yml).
  • Environment variables are set correctly.
  • Volume paths are correct.

Container monitoring​

Basic metrics​

# Container status
docker ps

# Resource usage
docker stats ai-proxy

# Processes running in the container
docker top ai-proxy

# Detailed inspection
docker inspect ai-proxy

Application Insights integration​

For full monitoring, use the Application Insights variant:

environment:
  - ApplicationInsights__ConnectionString=${APP_INSIGHTS_CONNECTION_STRING}

Backup and recovery​

Configuration backup​

# Configuration files backup
$backupDate = Get-Date -Format "yyyyMMdd"
Copy-Item .\aiconfiguration.json ".\backups\aiconfiguration_$backupDate.json"
Copy-Item .\certificates\* ".\backups\certificates_$backupDate\"

Configuration restore​

# Backup restore
$restoreDate = "20260115"
Copy-Item ".\backups\aiconfiguration_$restoreDate.json" .\aiconfiguration.json
Copy-Item ".\backups\certificates_$restoreDate\*" .\certificates\