Deployment¶

An Apilane Instance consists of 2 services that can be deployed in any environment:

Docker¶

Execute the provided docker-compose.yaml using the command:

docker-compose -p apilane up -d

This will set up both the Portal and the API services on Docker. You may then access the portal on http://localhost:5000.

Docker images¶

Both images are based on the official mcr.microsoft.com/dotnet/aspnet:8.0 runtime image. The build process uses a multi-stage Dockerfile with the mcr.microsoft.com/dotnet/sdk:8.0 image for compilation.

Volumes¶

Both services use persistent volumes to store data:

Kubernetes¶

Apilane can be deployed to Kubernetes, on premise or in any cloud provider. There are many deployment configurations required so it is impossible to provide a commonly acceptable YAML sample.

Multi-server setup¶

An Apilane Instance can consist of more than one API server. For example, you might have separate servers for testing and production. Visit the Server page for more details on this concept.

Health checks¶

Both services expose health check endpoints that can be used by load balancers, Kubernetes probes, or monitoring systems:

The API service readiness check includes a Portal connectivity check — the API must be able to reach the Portal to function correctly.

Example Kubernetes probes¶

livenessProbe:
  httpGet:
    path: /health/liveness
    port: 5001
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health/readiness
    port: 5001
  initialDelaySeconds: 15
  periodSeconds: 10

Additional endpoints¶

The API service exposes utility endpoints:

Observability¶

Logging¶

Both services use Serilog for structured logging. Logging configuration is driven by appsettings.{Environment}.json via the Serilog configuration section.

Metrics and tracing¶

The API service supports OpenTelemetry for metrics and distributed tracing:

Orleans Dashboard¶

The API uses Microsoft Orleans for distributed actor state management. Orleans requires a clustering provider for multi-server deployments. The system supports three clustering options with automatic fallback:

1. Localhost (default) - For single-server or development environments
2. Redis - For production multi-server deployments using Redis
3. AdoNet - For production multi-server deployments using SQL databases (SQL Server, MySQL, PostgreSQL)

Clustering Configuration¶

The clustering behavior is configured via the Clustering section in appsettings.{Environment}.json:

"Clustering": {
  "ClusterId": "apilane_api_cluster",
  "ServiceId": "apilane_api_service",
  "Type": "Localhost",
  "SiloPort": 11111,
  "GatewayPort": 30000,
  "DashboardPort": 8080
}

Configuration Options¶

Redis Clustering¶

For production deployments with multiple API instances, configure Redis clustering:

"Clustering": {
  "ClusterId": "apilane_api_cluster",
  "ServiceId": "apilane_api_service",
  "Type": "Redis",
  "SiloPort": 11111,
  "GatewayPort": 30000,
  "DashboardPort": 8080,
  "Redis": {
    "ConnectionString": "localhost:6379"
  }
}

AdoNet Clustering¶

For production deployments using SQL databases:

"Clustering": {
  "ClusterId": "apilane_api_cluster",
  "ServiceId": "apilane_api_service",
  "Type": "AdoNet",
  "SiloPort": 11111,
  "GatewayPort": 30000,
  "DashboardPort": 8080,
  "AdoNet": {
    "ConnectionString": "Server=localhost;Database=OrleansDb;User Id=sa;Password=YourPassword;",
    "Invariant": "System.Data.SqlClient"
  }
}

Supported Invariants: - System.Data.SqlClient - SQL Server - MySql.Data.MySqlClient - MySQL - Npgsql - PostgreSQL

Database Setup: The database and tables must be created before starting the API. See Orleans ADO.NET documentation for setup scripts.

Clustering Type Selection Logic¶

If no Clustering section is present in configuration, the system defaults to Localhost clustering.

If the Type is specified, the system attempts to use that clustering provider. If the required configuration is missing (e.g., Redis.ConnectionString for Redis type), the system throws an exception at startup.

The Orleans cluster exposes a dashboard (default port 8080) that can be useful for debugging in development environments.

Production considerations¶

• CORS: The API allows all origins, methods, and headers by default. For production, consider placing the API behind a reverse proxy (e.g., Nginx, Traefik) with stricter CORS policies.
• File caching: File downloads (via /files/download) are served with a Cache-Control: max-age=31536000 (1 year) header for optimal caching.
• Thread pool: Both services support a MinThreads environment variable to tune the .NET thread pool minimum worker threads for high-throughput scenarios.
• Blocked file extensions: The API service has a configurable list of invalid file extensions (InvalidFilesExtentions) to prevent uploading potentially dangerous files.
• InstallationKey: The InstallationKey must be the same value for both Portal and API — it is used for secure communication between the two services.