Docs

Self-Hosting Quickstart

From nothing to a running server.

Requirements

Docker and Docker Compose, and a host with a stable address that your devices can reach. The composition is four services plus PostgreSQL.

1. Clone

$ git clone -b v0.27.4 https://github.com/shellhub-io/shellhub.git
$ cd shellhub

Every release is on the releases page if you need a different one.

2. Generate keys

$ make keygen

This creates three secrets — the API key pair and the SSH host key — which are mounted as Docker secrets.

Back these up. Regenerating the SSH host key changes the server’s host key, and every SSH client that has connected before will refuse to connect until its known-hosts entry is cleared.

3. Configure

Never edit .env — it carries the defaults and an upgrade will overwrite it. Put your settings in .env.override, which is read last and wins:

$ touch .env.override
# .env.override
SHELLHUB_DOMAIN=shellhub.example.com
SHELLHUB_AUTO_SSL=true
SHELLHUB_POSTGRES_PASSWORD=<something-that-is-not-admin>

At minimum, set the domain and change the database password. Every variable is in Environment Variables.

4. Start

$ make start

This runs keygen if you have not, then brings the stack up detached.

5. Create the first account

The stack comes up with no users. The first one is created in the browser:

  1. Open the server’s address. Until the first account exists every path redirects to /setup.
  2. Enter a name, a username and an email. This user is the instance’s superadmin.
  3. Keep the suggested namespace or click Edit. Lowercase, no dots — it appears in every SSHID.
  4. Enter a password of at least 5 characters, and click Complete setup.

You are signed in. On Community that namespace is the namespace — Community is single-namespace, and the server refuses to create another. See Editions.

6. Connect a device

Nothing from here on is specific to self-hosting. The Quickstart installs the agent, accepts the device, opens a terminal on it and gives your team access to it.

Skip its account section — the setup screen just did that — and use your own address wherever it says cloud.shellhub.io.

Managing the stack

$ make start           # bring it up
$ make stop            # stop it
$ make restart         # stop then start
$ ./bin/docker-compose ps
$ ./bin/docker-compose logs -f

What you just deployed

  • A gateway, terminating TLS and fronting web traffic
  • A server, carrying the API and the SSH endpoint in one process
  • The web console
  • PostgreSQL, holding everything that matters
  • A cache and task queue

The SSH port is published by the server, not the gateway. That matters if you put a load balancer in front. See Ports and Connectivity.

Before you depend on it

  1. Decide who owns the server, by name.
  2. Decide where the database backup goes, and restore it once to prove it works. See Backup.
  3. Decide whether an outage is acceptable, or whether you need more than one host.
  4. Read Ports and Connectivity, so the network conversation happens once rather than during an incident.

Where to go next

esc