# OSC-Docker

Docker image for the Open Stage Control node-only release.

This image uses the upstream release artifact instead of building Electron from source. I verified on May 10, 2026 that Framagit's current release is `v1.30.3`, and that it publishes a `Node.js` package at:

`https://openstagecontrol.ammd.net/packages/open-stage-control_1.30.3_node.zip`

Source project:

`https://framagit.org/jean-emmanuel/open-stage-control`

## Getting Started

If you just want to run Open Stage Control, use the prebuilt image:

`git.f-40.com/aiden/osc-docker:latest`

### Option 1: Docker Run

1. Create folders for config and session files:

```bash
mkdir config data
```

2. Start the container:

```bash
docker run --rm \
  --name open-stage-control \
  -p 8080:8080/tcp \
  -p 8080:8080/udp \
  -v "${PWD}/config:/config" \
  -v "${PWD}/data:/data" \
  git.f-40.com/aiden/osc-docker:latest
```

3. Open this in your browser:

`http://localhost:8080`

### Option 2: Docker Compose

1. Make sure `compose.yaml` is in the folder you are working from.

2. Create folders for persistent data:

```bash
mkdir config data
```

3. Start it:

```bash
docker compose up -d
```

4. Open:

`http://localhost:8080`

### Where Your Files Go

- `./config`: Open Stage Control config and cache data
- `./data`: sessions, themes, and other files you want Open Stage Control to access

## Build

```bash
docker build -t open-stage-control .
```

To target a different upstream release:

```bash
docker build \
  --build-arg OPEN_STAGE_CONTROL_VERSION=1.30.3 \
  -t open-stage-control .
```

## Run From Source Image

```bash
docker run --rm \
  -p 8080:8080/tcp \
  -p 8080:8080/udp \
  -v "${PWD}/config:/config" \
  -v "${PWD}/data:/data" \
  open-stage-control
```

Then open:

`http://localhost:8080`

## Docker Compose

```bash
docker compose up
```

The included compose file uses the published image directly:

`git.f-40.com/aiden/osc-docker:latest`

## Gitea Actions

The repo includes a Gitea Actions workflow at `.gitea/workflows/docker-publish.yml`.

It will:

- build on pushes to `main`
- allow manual runs with `workflow_dispatch`
- poll the upstream Open Stage Control releases API once a week
- build and push a new image only when a new upstream release tag is found

Required repository secrets:

- `USER`: registry username
- `TOKEN`: registry token or PAT for `git.f-40.com`

## Environment Variables

- `OSC_PORT`: HTTP port. Default `8080`.
- `OSC_OSC_PORT`: OSC UDP input port. Default `8080`.
- `OSC_TCP_PORT`: Optional OSC TCP input port.
- `OSC_CACHE_DIR`: Config/cache path inside the container. Default `/config`.
- `OSC_REMOTE_ROOT`: File browser root inside the container. Default `/data`.
- `OSC_LOAD`: Optional session file to auto-load.
- `OSC_STATE`: Optional state file to auto-load.
- `OSC_CUSTOM_MODULE`: Optional custom module path.
- `OSC_THEME`: Optional theme path or theme name.
- `OSC_AUTHENTICATION`: Optional `user:password`.
- `OSC_CLIENT_OPTIONS`: Optional single `key=value` client option. For multiple client options, pass extra CLI args after the image name.
- `OSC_READ_ONLY`: Set to `true` to disable editing/saving.
- `OSC_USE_SSL`: Set to `true` to enable HTTPS.
- `OSC_DEBUG`: Set to `true` to log OSC traffic.
- `OSC_NO_QRCODE`: Set to `true` to suppress QR output.

## Extra CLI Arguments

You can still pass native Open Stage Control arguments after the image name:

```bash
docker run --rm -p 8080:8080/tcp -p 8080:8080/udp open-stage-control --send 192.168.1.50:9000
```