---
name: viber-relay-deploy
description: Deploy, verify, update, or troubleshoot the self-hosted Viber Relay Server used for mac-server-mobile forwarding. Use when a user wants to install the relay server on an Ubuntu VPS, Docker host, cloud VM, or local Linux server; configure VIBE_RELAY_URL for desktop; validate /health, /api/v1/compat, and network status; or diagnose relay connectivity.
metadata:
  short-description: Deploy Viber Relay Server on a VPS
---

# Viber Relay Deploy

Use this skill to deploy the Viber Relay Server, the lightweight Go service that forwards the `mac -> relay server -> mobile` path for Viber Today.

## Inputs

Collect or infer:

- SSH host/IP, SSH user, and private key path.
- Public URL. Use `https://domain` when a domain and TLS are already available; otherwise use `http://<server-ip>:8080`.
- Port, default `8080`.
- Optional relay token. Do not print token values in summaries or logs.
- Optional repo/ref override. Default installer repo is `https://github.com/toeveryday/vibe-mobile` on `main`.

## Deployment Workflow

1. Confirm SSH works without exposing private key contents:

```bash
ssh -i <key.pem> <user>@<host> 'hostname && uname -a'
```

2. On Ubuntu, install Docker only if missing. Prefer Docker's official apt repo and the Compose plugin. If Docker is already installed and `docker compose version` works, skip this step.

3. Open the relay port only if a firewall is active:

```bash
sudo ufw status
sudo ufw allow 8080/tcp
```

4. Run the hosted installer on the remote host. Replace placeholders before running:

```bash
curl -fsSL https://viber.today/install-relay-server.sh | env \
  VIBE_RELAY_PUBLIC_URL=http://<server-ip>:8080 \
  VIBE_RELAY_PORT=8080 \
  sh
```

For authenticated relays, pass `VIBE_RELAY_TOKEN=<token>` in the same `env` command. Avoid echoing token values.

5. Verify the service from the agent machine, not only from inside SSH:

```bash
curl -fsS http://<server-ip>:8080/health
curl -fsS http://<server-ip>:8080/api/v1/compat
curl -fsS http://<server-ip>:8080/api/v1/network/status
```

Expected `/api/v1/compat` includes `schemaVersion`, `protocolVersion`, `minClientProtocolVersion`, and `capabilities`.

6. Give the user the desktop command:

```bash
VIBE_RELAY_URL=http://<server-ip>:8080 yarn workspace desktop dev:electron
```

If a token was configured:

```bash
VIBE_RELAY_URL=http://<server-ip>:8080 VIBE_RELAY_TOKEN=<token> yarn workspace desktop dev:electron
```

## Update Workflow

Use the installer again with the same env values. It is idempotent and rebuilds the Docker service in `$HOME/.vibe-relay/src`.

```bash
curl -fsSL https://viber.today/install-relay-server.sh | env \
  VIBE_RELAY_PUBLIC_URL=http://<server-ip>:8080 \
  VIBE_RELAY_PORT=8080 \
  sh
```

Then verify `/api/v1/compat` and `/api/v1/network/status`.

## Troubleshooting

- If `/health` fails: check cloud security group, `ufw`, Docker status, and port binding with `ss -ltnp | grep 8080`.
- If WebSocket fails behind a reverse proxy: enable `Connection: Upgrade` and `Upgrade: websocket`; set proxy idle timeout to at least 60s.
- If mobile cannot add the server: confirm the QR payload contains a public relay URL, the desktop is connected to `/api/v1/rooms/<room>/ws`, and `/api/v1/network/status` shows the desktop client in that room.
- If protocol negotiation fails: compare client `protocol_version` and server `/api/v1/compat.minClientProtocolVersion`.
- For logs:

```bash
cd "$HOME/.vibe-relay/src" && docker compose -f docker-compose.relay.yml logs -f relay-server
```

## Final Response Checklist

Report:

- Public relay URL.
- Health, compat, and network status results.
- Whether Docker/system firewall changes were made.
- Desktop launch command.
- Any remaining blocker, such as DNS/TLS not configured or a locked mobile device.