# 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](https://docs.docker.com/get-started/get-docker/)
- Unix-like terminal with Make installed (use WSL2 for Windows)

## Getting Started

### 1. Clone the Repository

```bash
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

```bash
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`.

```bash
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](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS) in
`certs/nss/`, which must be installed on each AIM 6.2+ client.

```bash
make docker-nss
```

### 5. Start the Server

```bash
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](../README.md#-management-api).

### 6. Client Configuration

#### Certificate Database

Follow the [AIM 6.x client setup instructions](AIM_6_7.md#aim-62-75-setup) 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
```