mk6i-open-oscar-server/docs/DOCKER.md

Open OSCAR Server Docker Setup

This guide explains how to set up an SSL-enabled instance of Open OSCAR Server using Docker.

Prerequisites

• Git
• Docker Desktop
• Unix-like terminal with Make installed (use WSL2 for Windows)

Getting Started

1. Clone the Repository

git clone https://github.com/mk6i/open-oscar-server.git
cd open-oscar-server

2. Build Docker Images

This builds Docker images for:

• Certificate generation
• SSL termination and HTTP routing (nginx, ports 80/443/5193)

• The Open OSCAR Server runtime

  make docker-images
  

3. Configure SSL Certificate

Option A: Generate a Self-Signed Certificate

If you don't have an SSL certificate, you can generate a self-signed certificate. The following creates a certificate under certs/server.pem.

make docker-cert OSCAR_HOST=ras.dev

Replace ras.dev with the hostname clients will use to connect.

Option B: Use an Existing Certificate

If you already have an SSL certificate, place the PEM-encoded file at:

certs/server.pem

4. Generate NSS Certificate Database

This creates the NSS certificate database in certs/nss/, which must be installed on each AIM 6.2+ client.

make docker-nss

5. Start the Server

make docker-run OSCAR_HOST=ras.dev

Replace ras.dev with the hostname clients will use to connect.

By default, you can enter any screen name and password at the AIM sign-in screen to auto-create an account.

Account auto-creation is meant to be a convenience feature for local development. In a production deployment, you should set DISABLE_AUTH=false in config/ssl/settings.env to enforce account authentication. User accounts can be created via the Management API.

6. Client Configuration

Certificate Database

Follow the AIM 6.x client setup instructions to install the certs/nss/ database on each client.

To make distribution easier, nginx serves the database files at http://<OSCAR_HOST>/certs/nss/ (e.g., http://ras.dev/certs/nss/), so clients can download them directly from the server.

Resolving Hostname

If OSCAR_HOST (e.g., ras.dev) is not a real domain with DNS configured, you'll need to add it to each client's hosts file so clients can resolve it.

• Linux/macOS: /etc/hosts
• Windows: C:\Windows\System32\drivers\etc\hosts

Add a line like this, replacing the IP with your server's IP address:

127.0.0.1 ras.dev