Installing on a Linux Server

install.sh downloads the release binary, checks its sha256 digest, creates the admin account and runs r3v3rs3 as a systemd service. One command installs it, and the same command upgrades it later.

Before You Start

The script needs:

• Linux with a running systemd. It stops on another init system.
• The x86_64 or the aarch64 architecture. No release binary exists for another one.
• root, and the commands curl, tar, xz, sha256sum and systemctl.

Step 1: Run the Script

$ curl -fsSL https://raw.githubusercontent.com/KilimcininKorOglu/r3v3rs3/main/install.sh | sudo bash

The script asks one question:

1. Admin WebUI address. The default is 127.0.0.1:46492, so the panel answers only on the server itself. Write 0.0.0.0:46492 only when a firewall or a VPN protects that port.

The last step of an install creates the admin account admin. Without a --password option the script generates a strong random password and prints it once:

r3-server v2.6.7 is running.

  WebUI:    http://127.0.0.1:46492/
  Server:   /usr/local/bin/r3-server
  Agent:    /usr/local/bin/r3-agent
  CLI:      /usr/local/bin/r3
  Config:   /etc/r3v3rs3
  Logs:     /var/log/r3v3rs3 and journalctl -u r3-server
  Service:  systemctl status|restart|stop r3-server
  Add user: /usr/local/bin/r3-server add-user --config-dir /etc/r3v3rs3 <name>

  Admin:    admin
  Password: C579ts1HwZwMB2DpbtvhDTMk

  The script printed the password only here. Store it in a password manager now.

Pass --password to choose the password of the new account:

$ curl -fsSL https://raw.githubusercontent.com/KilimcininKorOglu/r3v3rs3/main/install.sh \
    | sudo bash -s -- --password s3cret-PASSWORD

An upgrade keeps the existing accounts and prints no password. The script opens the WebUI port in the local firewall when the address binds beyond the loopback interface: it adds a rule to a running firewalld or an active ufw, and otherwise inserts an iptables accept rule when a catch-all REJECT or DROP rule would block the port, and saves the rule with netfilter-persistent when that tool exists.

All options also work without a question, for an unattended install:

$ curl -fsSL https://raw.githubusercontent.com/KilimcininKorOglu/r3v3rs3/main/install.sh \
    | sudo bash -s -- --version 2.6.7 --webui 0.0.0.0:46492

Step 2: Check the Service

$ systemctl is-enabled r3-server
enabled
$ systemctl is-active r3-server
active
$ curl -o /dev/null -w '%{http_code}\n' http://127.0.0.1:46492/
200

The script writes /etc/systemd/system/r3-server.service:

[Service]
Type=simple
Environment=R3V3RS3_CONFIG_DIR=/etc/r3v3rs3
Environment=R3V3RS3_LOG_DIR=/var/log/r3v3rs3
Environment=R3V3RS3_WEBUI=127.0.0.1:46492
ExecStart=/usr/local/bin/r3-server start
KillSignal=SIGINT
Restart=on-failure
RestartSec=5
LimitNOFILE=1048576

KillSignal=SIGINT matters: r3-server shuts down gracefully on SIGINT. LimitNOFILE=1048576 raises the file descriptor limit, because each connection needs one.

The service runs as root, so r3-server binds a port below 1024 without another setting.

Step 3: Open the Panel

The default address answers only on the server. Reach it through SSH instead of publishing the port:

$ ssh -L 46492:127.0.0.1:46492 user@your-server

Open http://localhost:46492/ and sign in with the account of Step 1. Getting Started continues with the first port and the first proxy.

Where the Files Are

journalctl -u r3-server shows the server log. /etc/r3v3rs3/r3v3rs3.db holds configuration and operational state, and r3v3rs3.key holds the master encryption key, so back up the whole directory and protect the backup.

Upgrade

Run the same command again:

$ curl -fsSL https://raw.githubusercontent.com/KilimcininKorOglu/r3v3rs3/main/install.sh | sudo bash

• The script replaces the binary with a rename, because the running service holds the old file open.
• It keeps the configuration and the accounts. It creates no second account.
• The WebUI question offers the address of the installed service as its default, so pressing Enter keeps it.
• It restarts the service and waits until the WebUI answers. When the WebUI stays silent for 30 seconds, it prints systemctl status and the last 50 journal lines, then stops.

Pin a release with --version 2.6.7 when you upgrade a fleet in steps.

Remove

$ sudo systemctl disable --now r3-server
$ sudo rm /etc/systemd/system/r3-server.service /usr/local/bin/r3-server /usr/local/bin/r3-agent /usr/local/bin/r3
$ sudo systemctl daemon-reload

This leaves /etc/r3v3rs3 and /var/log/r3v3rs3. Delete them only when you keep no certificate and no account.

Install an Agent

An agent target of the deployment platform runs apps on another server. On that server Docker Engine must run. On the master, enable the platform and set agent_port (and agent_host when the agents dial another name) in the [platform] section of config.toml, then restart it. Add the target on the Targets page of the master, then run the command that the page shows:

$ curl -fsSL https://raw.githubusercontent.com/KilimcininKorOglu/r3v3rs3/main/install.sh \
    | sudo bash -s -- --agent --master master.example.com:9443

The script asks for the enrollment token interactively without echoing it, keeping it out of process arguments and shell history. It installs the same binary and runs r3-agent as the systemd service r3-agent:

[Service]
Type=simple
Environment=R3V3RS3_AGENT_MASTER=master.example.com:9443
Environment=R3V3RS3_AGENT_DATA_DIR=/var/lib/r3v3rs3-agent
EnvironmentFile=-/var/lib/r3v3rs3-agent/token.env
ExecStart=/usr/local/bin/r3-agent
KillSignal=SIGINT
Restart=always
RestartSec=5

The token stays in token.env (mode 0600) only until the agent enrolls. The script waits up to 30 seconds for the enrollment, then deletes the file. When the enrollment fails, it prints the last 50 journal lines and stops. The Targets page shows the target as Online when the agent is connected.

To upgrade the agent, run the script again with --agent and without a token. To enroll the server again, create a New token on the Targets page and pass it with --token. To remove the agent:

$ sudo systemctl disable --now r3-agent
$ sudo rm /etc/systemd/system/r3-agent.service
$ sudo systemctl daemon-reload

/var/lib/r3v3rs3-agent holds the key of the agent and the files of its Compose apps.

Other Install Methods

• The releases page: pre-built release archives for a manual install. Put the binary in your PATH and write your own unit file.

Next Steps

• Getting Started: the first port and the first proxy.
• Configuration Files: what each file in the config directory holds.