Skip to main content

Installation

This guide walks you through installing AuthProxy in different environments. Choose the installation method that best fits your deployment requirements.

Prerequisites​

Before installing AuthProxy, ensure you have:

RequirementMinimumNotes
.NET 10 RuntimeASP.NET Core 10.0Required for all deployment methods
DatabaseSQL Server / SQLiteSee System Requirements. PostgreSQL is supported only as a generated read replica (DACPAC export); AuthProxy itself runs against SQL Server or SQLite.
Docker20.10+For containerized deployment (recommended)
Docker Compose2.0+For multi-service orchestration

Installation Methods​

AuthProxy uses a base image + binary mounting strategy. You don't build images per version — you mount pre-compiled binaries into a shared base container.

1. Pull the base image​

docker pull mcr.microsoft.com/dotnet/aspnet:10.0-alpine

2. Create the project directory structure​

mkdir -p /projects/myproject/{configs,AuthProxy/1.0.0}

3. Place binaries and configuration​

Copy the published AuthProxy binaries to /projects/myproject/AuthProxy/1.0.0/ and create the configuration file:

# Place appsettings.json in configs/
cp appsettings.json /projects/myproject/configs/authproxy.json

4. Run with Docker Compose​

Create docker-compose.yml:

services:
  authproxy:
    image: mcr.microsoft.com/dotnet/aspnet:10.0-alpine
    container_name: myproject-authproxy
    ports:
      - "8001:80"
    volumes:
      - /projects/myproject/AuthProxy/1.0.0:/app
      - /projects/myproject/configs/authproxy.json:/app/appsettings.json
    entrypoint: ["dotnet", "AuthProxy.dll"]
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:80/health"]
      interval: 30s
      timeout: 3s
      retries: 3
    restart: unless-stopped
    networks:
      - myproject

networks:
  myproject:
    driver: bridge
docker compose up -d

4a. Mono-proxy with local file storage​

For a single AuthProxy instance, store attachment bytes on local disk and mount that directory as a persistent Docker volume.

docker-compose.yml:

services:
  authproxy:
    image: mcr.microsoft.com/dotnet/aspnet:10.0-alpine
    container_name: myproject-authproxy
    ports:
      - "8001:80"
    volumes:
      - /projects/myproject/AuthProxy/1.0.0:/app
      - /projects/myproject/configs/authproxy.json:/app/appsettings.json
      - /projects/myproject/storage/authproxy-files:/var/lib/authproxy/files
    entrypoint: ["dotnet", "AuthProxy.dll"]
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
    restart: unless-stopped

appsettings.json:

{
  "ServiceId": 10,
  "ServiceName": "AuthProxy",
  "ServerOrigin": "https://app.example.com",
  "ProjectName": "MyProject",
  "CoreApiKey": "your_secure_api_key_for_internal_communication",
  "DBConnections": {
    "GateDB": "Server=sql;Database=authproxy_db;User Id=authproxy_user;Password=your_password;TrustServerCertificate=true;Encrypt=true;"
  },
  "FIDO2": {
    "serverDomain": "app.example.com",
    "serverName": "My App",
    "origins": ["https://app.example.com"]
  },
  "LocalFileStoragePath": "/var/lib/authproxy/files"
}

Important:

  • The mounted host directory must be writable by the container user.
  • Files are stored as {LocalFileStoragePath}/{owner}/{fileId}.
  • LocalFileStoragePath is the recommended storage mode for mono-proxy deployments.
  • This controls file byte storage only. File metadata and attachment lifecycle still go through the Chat module.
  • Do not configure FileServers when local disk storage is the intended backend.

5. Verify the installation​

# Check container status
docker ps | grep authproxy

# Check health endpoint
curl http://localhost:8001/health

# Check service info
curl http://localhost:8001/auth/v1/get_info

A successful response from get_info will return the service version, project name, and available authentication methods.

Method 2: Standalone (.NET)​

For development or environments without Docker:

1. Install .NET 10 SDK​

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y dotnet-sdk-10.0

# Or download from https://dotnet.microsoft.com/download/dotnet/10.0

2. Run AuthProxy directly​

cd /path/to/AuthProxy/binaries
dotnet AuthProxy.dll

AuthProxy will start on port 80 by default. Override with:

dotnet AuthProxy.dll --urls "http://0.0.0.0:5000"

Database Setup​

AuthProxy requires a database. The tables are created automatically on first launch if they don't exist.

SQL Server / SQL Server Express (Production)​

{
  "DBConnections": {
    "GateDB": "Server=localhost;Database=authproxy_db;User Id=authproxy_user;Password=your_password;TrustServerCertificate=true;Encrypt=true;"
  }
}

SQLite (Development / Standalone)​

{
  "DBConnections": {
    "GateDB": "Data Source=authproxy.db"
  }
}

SQLite requires no additional setup — the database file is created automatically.

Minimum Configuration​

Create appsettings.json with the minimum required settings:

{
  "ServiceId": 10,
  "ServiceName": "AuthProxy",
  "ServerOrigin": "https://yourdomain.com",
  "ProjectName": "MyProject",
  "CoreApiKey": "your_secure_api_key_for_internal_communication",
  "DBConnections": {
    "GateDB": "Server=localhost;Database=authproxy_db;User Id=sa;Password=your_password;TrustServerCertificate=true;"
  },
  "FIDO2": {
    "serverDomain": "yourdomain.com",
    "serverName": "AuthProxy",
    "origins": ["https://yourdomain.com"]
  }
}

For a complete configuration reference, see the Configuration guide.

Post-Installation​

After successful installation:

  1. Access the admin panel at http://your-host/ProxyAdmin
  2. Configure routes — add backend services in the Route Map admin page
  3. Set up authentication — enable desired auth methods (FIDO2, OAuth, etc.)
  4. Deploy PWA frontends — place built PWA files in wwwroot/

Troubleshooting​

Container won't start​

# Check logs
docker logs myproject-authproxy

# Common issues:
# - Database connection refused: ensure DB is reachable from container network
# - Port already in use: change host port mapping
# - Missing DLLs: verify all binaries are in the mounted volume

Database connection fails​

  • Verify the connection string in appsettings.json
  • Ensure the database server is accessible from the container network
  • For Docker: use the container name or Docker network IP, not localhost

Health check fails​

  • The /health endpoint requires the application to be fully started
  • First startup may take longer due to database table creation
  • Check application logs for startup errors

Next Steps​