Relay Deployment Guide (Oracle Cloud Free Tier)

You'll need:

• An Oracle Cloud account (oracle.com/cloud/free) — identity verification requires a card, but Always Free resources are never charged.
• An SSH key pair to log into the instance (ssh-keygen locally if you don't have one).
• About 20 minutes.

01.1 — Start instance creation

1. Go to Oracle Cloud Console → Compute → Instances → Create Instance
2. Name it: netcrafter-relay

01.2 — Choose the image

1. Under Image, click Change Image
2. Select: Canonical Ubuntu 22.04 (not 20.04, not Minimal, not aarch64)
3. Confirm it shows "Always Free eligible"

01.3 — Choose the shape

Two Always Free shapes are available:

Option A — VM.Standard.A1.Flex (Ampere ARM)

• Up to 4 OCPU / 24 GB RAM free
• Recommended: 2 OCPU / 12 GB RAM
• Better performance for coturn
• Frequently shows "Out of capacity" error — see Troubleshooting below

Option B — VM.Standard.E2.1.Micro (AMD x86)

• 1 OCPU / 1 GB RAM
• Always available — no capacity issues
• Sufficient for NetCrafter Relay (2–4 players typical, up to 8–10)
• Recommended if A1 is unavailable

To find these shapes:

1. Click Shape series → Specialty and previous generation
2. Look for shapes marked Always Free-eligible
3. Select VM.Standard.A1.Flex OR VM.Standard.E2.1.Micro

01.4 — Configure networking

Do not skip any step:

1. Under Primary VNIC → Virtual cloud network, select Create new virtual cloud network
2. Enter a name: netcrafter-vcn
3. Under Subnet, select Create new public subnet
4. Enter a name: public-subnet
5. Enter CIDR block: 10.0.0.0/24
6. Under Private IPv4 address, select Automatically assign private IPv4 address
7. Under Public IPv4 address, select Automatically assign public IPv4 address

01.4a — Create Internet Gateway and Route Table

After creating your VCN:

1. Go to Networking → Virtual Cloud Networks → netcrafter-vcn
2. In the left menu click Internet Gateways
3. Click Create Internet Gateway
4. Name: netcrafter-igw
5. Compartment: your root compartment
6. Click Create Internet Gateway

Then add the route rule:

1. In the left menu click Route Tables
2. Click Default Route Table for netcrafter-vcn
3. Click Add Route Rules
4. Fill in:
   • Target Type: Internet Gateway
   • Destination CIDR Block: 0.0.0.0/0
   • Target Internet Gateway: netcrafter-igw
5. Click Add Route Rules

Without this route rule, outbound traffic from your instance cannot reach the internet and inbound connections will time out.

01.5 — Add SSH keys

1. Under Add SSH keys, select Generate a key pair for me
2. Click Download private key — saves as ssh-key-YYYY-MM-DD.key
3. Click Download public key — saves as ssh-key-YYYY-MM-DD.key.pub
4. Store both files safely: C:\Users\YourName\.ssh\

The public key field will be automatically populated after downloading.

Open required ports in the Security List

While you have the Security List open, add ingress rules for coturn:

Go to: Networking → Virtual Cloud Networks → netcrafter-vcn → public-subnet → Security Lists → Default Security List → Add Ingress Rules

Add these rules (one at a time):

01.6 — Boot volume

Leave all boot volume settings as default:

• Do not check custom boot volume size
• Do not check in-transit encryption
• Do not attach block volumes

01.7 — Review and create

Confirm:

• Image: Canonical Ubuntu 22.04
• Shape: VM.Standard.A1.Flex or VM.Standard.E2.1.Micro
• Public IPv4 address: Yes
• SSH keys: present

Click Create.

Wait 1-2 minutes for status to change from Provisioning to Running.

Note the Public IP address shown on the instance details page.

Troubleshooting — Out of Capacity

If you see:

"Out of capacity for shape VM.Standard.A1.Flex in availability domain AD-1"

Try these in order:

1. Change availability domain — try AD-2 or AD-3 instead of AD-1
2. Remove fault domain — set to "Let Oracle choose the best fault domain"
3. Switch to E2.1.Micro — under Shape, select Specialty and previous generation, then pick VM.Standard.E2.1.Micro. Always available and sufficient for NetCrafter Relay.
4. Retry later — Oracle releases A1 capacity randomly. Try again in 30-60 minutes or the following morning.

Troubleshooting — SSH Connection Timed Out

SSH times out even though port 22 is in the Security List. This is almost always caused by a missing Internet Gateway or route rule.

Check this in order:

1. Go to Networking → Virtual Cloud Networks → netcrafter-vcn
2. Click Internet Gateways in the left menu
   • If NONE exists → create one named netcrafter-igw (see Section 01.4a)
3. Click Route Tables → Default Route Table
   • Confirm there is a rule with: Destination 0.0.0.0/0, Target Internet Gateway
   • If missing → Add Route Rules with these values

Sections 04-09 below install and configure coturn and the rendezvous service by hand, one SSH command at a time — that's still exactly what happens, and it's worth reading if you want to understand or customize any of it. But you don't have to type it all in yourself: install-relay-server.sh, shipped alongside the other server files, runs the entire sequence in one pass and ends with both services running, enabled on boot, and verified.

It does not change the self-hosted architecture — you're still running your own server, on your own instance. It only automates the setup.

03.1 — Copy the files onto the instance

Three files ship together at Assets/PivecLabs/NetCrafterRelay/ServerTools/:

install-relay-server.sh
rendezvous_server.py
netcrafter-relay-rendezvous.service

Copy all three (adjust the source path to wherever your Unity project lives):

scp -i /path/to/your_private_key \
  "Assets/PivecLabs/NetCrafterRelay/ServerTools/install-relay-server.sh" \
  "Assets/PivecLabs/NetCrafterRelay/ServerTools/rendezvous_server.py" \
  "Assets/PivecLabs/NetCrafterRelay/ServerTools/netcrafter-relay-rendezvous.service" \
  ubuntu@<PUBLIC_IP>:~/

03.2 — Run it

sudo bash ~/install-relay-server.sh

With no flags, it prompts for each value it can't detect itself (public/private IP are auto-detected via cloud metadata and ifconfig.me/interface routing, with a chance to confirm or override; the TURN shared secret defaults to a freshly generated random one). Pass -y/--yes to accept every detected/default value without prompting, or supply any value directly as a flag — --public-ip, --private-ip, --realm, --turn-username, --shared-secret, --rendezvous-port, --min-port, --max-port. Run --help for the full list.

Want to see exactly what it would do first, with no root and no changes to the real system? bash install-relay-server.sh --dry-run writes every generated file (turnserver.conf, the systemd unit, etc.) under a local ./netcrafter-relay-dry-run/ folder and echoes every privileged command instead of running it.

Step by step, a real (non-dry-run) run:

1. Installs coturn via apt.
2. Detects (or accepts as flags) public IP, private IP, realm, TURN username, and TURN shared secret — confirming each with you unless --yes is passed.
3. Writes /etc/turnserver.conf from those values — external-ip, lt-cred-mech, realm, user= — matching Section 06 below exactly.
4. Enables and starts the coturn systemd service.
5. Installs rendezvous_server.py to /opt/netcrafter-relay/ and the systemd unit to /etc/systemd/system/, creating the netcrafter-relay system user and /var/lib/netcrafter-relay-rendezvous data directory to match what the unit file expects (verified — no mismatch between the two).
6. Enables and starts the rendezvous systemd service.
7. Opens both services' ports via iptables (+ netfilter-persistent save), then detects whether this looks like an Oracle Cloud instance and prints an explicit reminder either way: cloud providers commonly enforce a separate, network-level firewall (Oracle's Security List, AWS Security Groups, etc.) that iptables cannot reach or open — that part is always manual, in your provider's console.
8. Verifies: curls the rendezvous service's endpoints (including a full host/join/peers round trip), checks coturn's systemd status, and runs a local turnutils_uclient credential smoke test if it's available — then prints a plain summary of what's running, on what ports, and the exact values to paste into Unity's Relay Settings.

That final summary looks like this (values will differ per instance):

========================================================
NetCrafter Relay server setup complete.

Running:
  coturn                       : UDP/TCP 3478, relay ports 49160-49200
  netcrafter-relay-rendezvous  : TCP 8787

Paste these into Unity -> NetCrafter Relay window -> Settings -> Relay Settings:

  Relay Host       : 192.0.2.10
  Relay Port       : 3478
  Rendezvous URL   : http://192.0.2.10:8787
  Credential Mode  : StaticSecret
  TURN Username    : netcrafter-relay
  Shared Secret    : <your generated or provided secret>

  NOTE: Rendezvous URL includes the http:// prefix, shown above -- Relay Host
  does NOT take one (TURN doesn't use a scheme). Paste Rendezvous URL exactly
  as printed, scheme included.

IMPORTANT -- cloud firewall (this script cannot reach this):
  This looks like an Oracle Cloud instance. The iptables rules above only
  cover this machine's own firewall -- Oracle's Security List is a SEPARATE
  network-level firewall that also must allow this traffic in, and this
  script has no way to reach or modify it. Open it yourself:
    Console -> Networking -> Virtual Cloud Networks -> your VCN ->
    Security Lists -> Add Ingress Rules:
      0.0.0.0/0  UDP+TCP  3478              TURN/STUN
      0.0.0.0/0  UDP      49160-49200       Relay ports
      0.0.0.0/0  TCP      8787              Rendezvous service
========================================================

A copy of the credential values is also saved to /root/netcrafter-relay-credentials.txt (mode 600).

Safe to re-run: useradd tolerates an existing user, config/service files are overwritten with the same content, and systemctl enable --now is idempotent — running it again against an already-configured instance re-confirms everything and exits the same way.

Oracle Cloud has two firewall layers, and both must allow the traffic — this is the most common thing people miss. (The rendezvous service gets its own port later, in Section 09 — same two-layer gotcha applies there too.)

(a) Security List (cloud-level, stateless)

Console → Networking → Virtual Cloud Networks → your VCN → Security Lists → the default security list → Add Ingress Rules:

A narrow relay port range (here, 41 ports) is enough for a handful of concurrent sessions (2–4 players typical, up to 8–10) and keeps the open-port surface small — widen it only if you expect many simultaneous sessions.

(b) The instance's own firewall

Oracle's Ubuntu images ship with iptables rules (via netfilter-persistent/oracle-cloud-agent) that block everything not explicitly allowed, on top of the Security List above. Open the same ports locally:

sudo iptables -I INPUT -p udp --dport 3478 -j ACCEPT
sudo iptables -I INPUT -p tcp --dport 3478 -j ACCEPT
sudo iptables -I INPUT -p udp --dport 49160:49200 -j ACCEPT

sudo apt install -y iptables-persistent   # if not already installed
sudo netfilter-persistent save

Edit /etc/turnserver.conf:

listening-port=3478
fingerprint
lt-cred-mech
realm=netcrafter.relay
user=netcrafter-relay:YOUR_SHARED_SECRET_HERE
min-port=49160
max-port=49200
external-ip=<PUBLIC_IP>/<PRIVATE_IP>
no-tls
no-dtls
log-file=/var/log/turnserver.log
simple-log
no-multicast-peers

• user=netcrafter-relay:YOUR_SHARED_SECRET_HERE — this is the StaticSecret long-term credential: a single username/password pair every peer uses. Pick a real random secret, not a password you use elsewhere.
• external-ip=<PUBLIC_IP>/<PRIVATE_IP> — Oracle instances have a private IP (find it with ip addr show, usually on ens3/eth0) behind a separately NAT'd public IP. This tells coturn to advertise the public IP in relayed-address attributes while binding to the private interface. Without this, peers receive an unreachable private IP and allocation succeeds but relaying silently fails.
• no-tls/no-dtls — keeps the MVP setup simple (plain UDP relay, matching StunTurnClient.cs, which doesn't do DTLS). Fine for a small co-op relay (2–4 players typical, up to 8–10); add TLS later if you want encrypted TURN control traffic.

The quickest way to verify coturn is working is using a free browser-based TURN checker — no extra software needed (no Linux-only tools like turnutils_uclient required).

1. Open this URL in your browser: webrtc.github.io trickle-ice sample
2. Scroll down to the ICE servers section
3. Remove any existing servers and add yours:

URI:      turn:YOUR_PUBLIC_IP:3478   (e.g. turn:92.5.181.120:3478)
Username: netcrafter-relay
Password: <your shared secret from turnserver.conf>

4. Click Add Server
5. Click Gather candidates
6. Wait 10-15 seconds

Join codes need a small lookup service so a host's relayed address can be found by a joiner (and vice versa) — coturn only relays traffic, it doesn't do address-book lookups. This section installs a minimal one on the same instance, listening on its own port, so you don't need to provision a second server.

09.1 — Open its port (both layers)

Pick a port not already used by coturn — this guide uses 8787.

(a) Security List:

Console → Networking → Virtual Cloud Networks → your VCN → Security Lists → the default security list → Add Ingress Rules:

(b) The instance's own firewall:

sudo iptables -I INPUT -p tcp --dport 8787 -j ACCEPT
sudo netfilter-persistent save

09.2 — Copy the rendezvous script onto the instance

The service is a single Python 3 file with no pip installs required — Ubuntu 22.04 ships Python 3 by default, and the script only uses the standard library (http.server, sqlite3).

It ships with NetCrafter Relay at:

Assets/PivecLabs/NetCrafterRelay/ServerTools/rendezvous_server.py
Assets/PivecLabs/NetCrafterRelay/ServerTools/netcrafter-relay-rendezvous.service

Copy both to the instance (from your local machine — adjust the source path to wherever your Unity project lives):

scp -i /path/to/your_private_key \
  "Assets/PivecLabs/NetCrafterRelay/ServerTools/rendezvous_server.py" \
  "Assets/PivecLabs/NetCrafterRelay/ServerTools/netcrafter-relay-rendezvous.service" \
  ubuntu@<PUBLIC_IP>:~/

09.3 — Install and start it as a systemd service

sudo mkdir -p /opt/netcrafter-relay
sudo mv ~/rendezvous_server.py /opt/netcrafter-relay/

sudo useradd --system --no-create-home --shell /usr/sbin/nologin netcrafter-relay || true
sudo mkdir -p /var/lib/netcrafter-relay-rendezvous
sudo chown -R netcrafter-relay:netcrafter-relay /var/lib/netcrafter-relay-rendezvous

sudo mv ~/netcrafter-relay-rendezvous.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netcrafter-relay-rendezvous
sudo systemctl status netcrafter-relay-rendezvous   # confirm "active (running)"

09.4 — Test it

curl http://<PUBLIC_IP>:8787/

Then confirm the actual join-code contract end to end (this is the same sequence NetCrafter Relay's generated code drives automatically — see RelayConnectionManager.tpl's HostSession()/JoinSession()/PollForPeers()):

# Simulate a host registering:
curl -X POST http://<PUBLIC_IP>:8787/host -d '{"relayedAddress":"1.2.3.4:5000"}'
# -> {"joinCode": "AB3F9", "userId": 0}

# Simulate a joiner resolving that code (use the joinCode from above):
curl -X POST http://<PUBLIC_IP>:8787/join/AB3F9 -d '{"relayedAddress":"5.6.7.8:6000"}'
# -> {"relayedAddress": "1.2.3.4:5000"}

# Simulate the host polling for peers:
curl http://<PUBLIC_IP>:8787/host/AB3F9/peers
# -> {"peers": ["5.6.7.8:6000"]}

In the NetCrafter Relay editor window → Settings → Relay Settings:

Rendezvous URL has no working default — the field is required and ships blank. Leaving it blank fails the join-code flow at runtime with a clear error rather than a silent hang; there is no Pivec Labs-hosted fallback to fall back to.

Click Save Settings. The generated RelayConnectionManager reads these values live from this same RelaySettings asset at runtime (via its connectionSettings field, auto-wired by Prefab Generator) — there's no need to regenerate code or recreate the prefab just because a value here changed.

• The shared secret lives only in the RelaySettings.asset ScriptableObject (Definitions/{Name}/RelaySettings.asset) — it is read live via connectionSettings.sharedSecret, never baked into generated C# source. Treat it as a low-value credential appropriate for a hobby/small-studio relay regardless — not a production secret, never one reused from elsewhere — but it won't end up committed to source control just because you committed generated code.
• Anyone who gets a copy of your RelaySettings.asset (or the RelayConnectionManager prefab referencing it) can see this secret and, in principle, allocate through your relay. For small co-op sessions (2–4 players typical, up to 8–10) the blast radius is small, but it's worth knowing. A production-grade setup would use RestApi credential mode — time-limited HMAC credentials minted by a rendezvous service — which is reserved for a future release and not yet implemented.
• The rendezvous service has no authentication beyond knowing the join code — anyone who guesses or brute-forces a 5-character code within its ~15 minute lifetime could poll its peer list. At 2-8 players and short-lived codes, this is a low-value target, matching the same posture already accepted for the TURN shared secret above.
• The rendezvous service's database is a single SQLite file at /var/lib/netcrafter-relay-rendezvous/rendezvous.db. It's designed to be disposable — only ever holds short-lived join codes — so there's no need to back it up.
• Always Free has an outbound data transfer allowance (10TB/month at time of writing) — comfortably enough for casual co-op traffic; keep an eye on it if you expect heavy use.
• Keep the instance patched: sudo apt update && sudo apt upgrade -y periodically.

• RestApi credential mode — time-limited HMAC-signed TURN credentials minted by a server-side service, instead of the single long-term StaticSecret used throughout this guide. Reserved for a future release; not yet implemented.
• TLS/HTTPS for either coturn (control channel) or the rendezvous HTTP service — both run plain UDP/HTTP here, matching the MVP posture described above. Add TLS yourself if you need encrypted control traffic for your use case.
• Scaling beyond a single instance — this guide is sized for a handful of concurrent sessions (2–4 players typical, up to 8–10) on one Always Free box, not a matchmaking service for many simultaneous games.
• Provisioning the instance itself, or your cloud provider's network-level firewall — install-relay-server.sh (Section 03) automates everything that happens on the instance over SSH. Creating the instance (Section 01) and opening ports in your provider's own console (Oracle's Security List or equivalent) both happen outside SSH, so no script — this one included — can reach or automate them.