shellgraph

Install the server

Build shellgraph-server, make the master key, then start the server behind TLS.

Before you start

  • To build: Go 1.27, Node.js 24, pnpm 11, and Podman for the image.
  • To run: one Linux machine (amd64 or arm64), or a container runtime.
  • An LDAP directory or an OIDC identity provider for the login. The server has no local users.

Build

  1. Clone the repository and go to it.

    git clone https://git.rda.run/shellgraph/server.git
cd server

  2. Build the binary. The UI is in the binary.

    make build

    The result is bin/shellgraph-server for linux/amd64. For arm64, use make build ARCH=arm64.

  3. Optional: build the container image shellgraph-server:<version>.

    make image

The binary is compiled for x86-64 v3 (AVX2, all CPUs since 2013). For an older CPU, use make build GOAMD64=v2.

Make the master key

The server encrypts the SSH private keys with a master key. Without the master key, the server cannot read the credentials.

  1. Make a key.

    shellgraph-server keygen

  2. Keep the key in a safe place.

  3. Put the key in the environment variable SHELLGRAPH_KEY of the server.

Configure the login

Configure LDAP, OIDC, or both, before the first start. If no login method is configured, the server does not start.

Start the server

  1. Set the variables.

    export SHELLGRAPH_KEY='<key>'
export SHELLGRAPH_ADMIN_GROUP=shellgraph-admins
export SHELLGRAPH_OIDC_ISSUER=https://id.example.net
export SHELLGRAPH_OIDC_CLIENT_ID='<client ID>'
export SHELLGRAPH_OIDC_CLIENT_SECRET='<client secret>'

  2. Start the server.

    shellgraph-server serve --db /var/lib/shellgraph/shellgraph.db --listen :8080

If a variable is missing or not valid, the server prints the problem and stops. For all flags and variables, see Command line and Environment variables.

Run in a container

The image has only the binary. It runs as the user 10001 and keeps the database in the volume /data.

  1. Put the variables in a file, one NAME=value on each line, for example /etc/shellgraph/env.

  2. Make the file readable only by root. It contains the master key and the login secrets.

    chmod 600 /etc/shellgraph/env

  3. Start the container.

    podman run -d --name shellgraph -p 8080:8080 --env-file /etc/shellgraph/env -v shellgraph-data:/data shellgraph-server:<version>

Use TLS

Use HTTPS between the collectors and the server. Do one of these:

  • Start the server with --tls-cert and --tls-key.
  • Put a reverse proxy with TLS in front of the server. The proxy must send the header X-Forwarded-Proto: https. Set SHELLGRAPH_PUBLIC_URL to the public URL, so that the OIDC callback and the map links are correct.

The collector refuses an http:// server URL, except for localhost and 127.0.0.1. Security gives the reason.

Do a health check

curl https://shellgraph.example.net/healthz

The server returns {"status":"ok","version":"<version>"}.

Back up

Back up the database file and the master key to different places.

  1. Make a copy of the database. The database uses WAL mode, so do not copy the file while the server runs. Use the SQLite backup command, or stop the server first.

    sqlite3 /var/lib/shellgraph/shellgraph.db ".backup /backup/shellgraph.db"

  2. Keep the master key in a different place, for example a password manager.