> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Develop with Gitpod

> For contributors who want a ready-made environment: open Routr in a Gitpod workspace and connect a local softphone to it over SSH.

Open Routr in a cloud workspace that builds and starts the server for you, then forward its SIP port to your computer so you can register a softphone.

## Prerequisites

* A [Gitpod](https://gitpod.io) account.
* An SSH key pair on your computer.
* A softphone that supports SIP over **TCP** (for example Zoiper or Blink).

## What the workspace runs

The repository's `.gitpod.yml` defines one task. On start it appends `etc/hosts.txt` to `/etc/hosts`, runs `npm run make` to build everything, and then runs `npm start`. That gives you the same Connect distribution as [running from source](/guides/run-from-source): two EdgePorts (ports `5060` to `5063` and `6060` to `6063`), the Message Dispatcher (`51901`), Location Service (`51902`), the Connect processor (`51904`), Registry, Requester, and the API Server with the YAML backend.

## Open and connect

**1. Start the workspace**

Open the workspace in your browser. The first build takes a few minutes:

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/fonoster/routr)

When it's ready you get an editor, a file explorer, and a terminal running `npm start`.

**2. Add your SSH key to Gitpod**

Print your public key. On Linux or macOS:

```bash theme={null}
cat ~/.ssh/id_rsa.pub
```

On Windows:

```text theme={null}
type %USERPROFILE%\.ssh\id_rsa.pub
```

If you don't have a key, create one:

```bash theme={null}
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
```

Paste the public key at [gitpod.io/user/keys](https://gitpod.io/user/keys).

![Gitpod SSH keys settings page with a field to add a public key](https://mintcdn.com/routr-docs/iaqIipuuzAjyl_cH/images/develop-with-gitpod/gitpod-account-keys.png?fit=max\&auto=format\&n=iaqIipuuzAjyl_cH\&q=85\&s=7e06d75e67a1be6972c506408e0fa4a3)

**3. Copy the SSH connection command**

Go to [gitpod.io/workspaces](https://gitpod.io/workspaces), open the **More** menu on your workspace, and select **Connect via SSH**. Copy the command it shows.

![Gitpod workspaces list with the More menu open and the Connect via SSH option](https://mintcdn.com/routr-docs/iaqIipuuzAjyl_cH/images/develop-with-gitpod/gitpod-workspace.png?fit=max\&auto=format\&n=iaqIipuuzAjyl_cH\&q=85\&s=c32b6ff108e67dc69be8dacb2140ffb8)

**4. Forward the SIP port**

Run the SSH command with `-L 5060:localhost:5060` appended. This forwards your local TCP port `5060` to the workspace:

```bash theme={null}
ssh <workspace-ssh-connection> -L 5060:localhost:5060
```

For example:

```bash theme={null}
ssh fonoster-routr-mn8nsx0d9px@fonoster-routr-mn8nsx0d9px.ssh.ws-us90.gitpod.io -L 5060:localhost:5060
```

Keep this session open while you test.

**5. Register a softphone**

Point a softphone at `localhost:5060` using **TCP**, domain `sip.local`, and one of the Agents defined in [`config/resources`](https://github.com/fonoster/routr/tree/main/config/resources) (for example user `1001`, password `1234`).

> [!TIP]
>
> The softphone shows as registered, and the workspace terminal logs the `REGISTER`.

## Change the data

The workspace uses the YAML backend (`simpledata`), so you don't create Domains or Agents with `rctl`. Edit the files in `config/resources` instead, then restart `npm start` to load them.

## Pitfalls

* **UDP doesn't work through the tunnel.** SSH port forwarding carries TCP only. Configure your softphone for TCP.
* **Java changes need a rebuild.** Nodemon reloads the Node.js services, but EdgePort and Requester need `npm run build:java` and a restart of `npm start`.
* **The TLS keystore isn't in the repository.** The task's `before` step copies `etc/certs/signaling.p12`, which isn't tracked. If EdgePort fails to start because of the keystore, create one as described in [Run Routr from source](/guides/run-from-source).

## Related

> **[Run Routr from source](/guides/run-from-source)**
>
> The same setup on your own machine.

> **[Contributing](/contributing)**
>
> How to send your changes upstream.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.