Getting Started
Coder is an open source platform for self-hosted cloud development environments. Developers get remote workspaces defined as code with Terraform templates, managed from a central web dashboard. Available as an open web service in Eyevinn Open Source Cloud, it runs the Coder control plane (dashboard and API) as a single instance backed by a PostgreSQL database. This tutorial walks you through the steps to get started.
Scope: this service is the control plane only. See Limitations before you plan on creating workspaces.
Prerequisites
- If you have not already done so, sign up for an Eyevinn OSC account
Coder needs a PostgreSQL database that must exist before you create the Coder instance.
Step 1: Create a PostgreSQL database
Navigate to the PostgreSQL service (see Service: PostgreSQL) and create an instance with:
- name: a name for the instance, for example
coderdb - PostgresPassword: a password, store it as a secret in the PostgreSQL service if you prefer
- PostgresDb (optional): a database name, for example
coder
Wait until the instance is running. Open the instance details and note the internal cluster hostname. It has the format <instance>.birme-osc-postgresql.svc.cluster.local. Use that hostname and port 5432 to build the connection URL:
postgres://<user>:<password>@<instance>.birme-osc-postgresql.svc.cluster.local:5432/coder?sslmode=disable
If the password contains special characters, percent-encode them in the URL.
Step 2: Store the connection URL as a secret
Navigate to the Coder service and go to the "Service Secrets" tab. Click "New Secret" and create:
coderdburl: the full PostgreSQL URL from Step 1
A {{secrets.NAME}} reference only works when it is the entire field value. Because the URL embeds a password, store the whole URL as one secret. Substituting a secret into only a part of the URL does not resolve.
Step 3: Create the Coder instance
Go to the "My coder" tab and click "Create coder". Fill in:
- Name: a name for your instance
- PgConnectionUrl:
{{secrets.coderdburl}} - AccessUrl (optional): leave empty to use the instance's own OSC address
- TelemetryEnable (optional): leave unset, telemetry is off by default
Click "Create" to launch your instance.
Step 4: Open the dashboard
Once the instance is running, open the instance URL in your browser while signed in to OSC. The Coder web dashboard loads.
OSC puts an authentication gate in front of all paths on the instance except /. Signed-in OSC users in a browser pass it.
Configuration
| Option | Required | Description |
|---|---|---|
| name | Yes | Instance name |
| PgConnectionUrl | Yes | PostgreSQL URL postgres://user:password@host:5432/dbname?sslmode=disable. Store the whole URL as one secret and reference it as {{secrets.NAME}}. |
| AccessUrl | No | Public URL of the instance, without a path. If empty, the instance's own OSC address is used. |
| TelemetryEnable | No | Boolean. Telemetry is off by default. |
The instance listens on port 8080 and is based on the official Coder v2.38.10 release.
Licensing
The Coder core is licensed under AGPL-3.0. The enterprise/ directory in the Coder repository is under a separate proprietary license. Those features are gated by a license key, and production use of them requires agreeing to Coder's Terms of Service.
Limitations
- This is the control plane only. Creating workspaces requires external provisioners and infrastructure, with Terraform templates targeting your own cloud, Kubernetes or Docker. OSC does not provide a Docker socket or Kubernetes access for this.
- The logs show one error line about embedded NATS pubsub having no cluster host. Coder falls back to PostgreSQL pubsub.
- The OSC authentication gate may block the Coder CLI and workspace agents that connect to
/api/v2. This has not been tested. - Tested on OSC: the instance starts, listens on port 8080, connects to the database and
/returns 200. - Not tested on OSC: first-user setup, login, templates, workspaces, the Coder CLI, external provisioners, persistence across restarts, and the effect of the authentication gate on the CLI and agents.