Install on one server

This page covers the all-in-one install: Gardience and its own Salt master on one Linux server. To use a Salt master you already run, see Attach to an existing Salt master. For a server with no internet access, see Install without internet access.

The quickest way: one command#

When you start a trial at gardience.com/trial (or after you buy), the page shows a command like this:

curl -fsSL https://gardience.com/i/YOUR-CODE | sudo bash

Run it on the server. It downloads the current release, checks it against the release checksum, adds your license, installs Docker if it is missing, and runs the installer described below with its default options. It prints the console address and the first admin password when it finishes. The command works for 24 hours; open your trial or order page again for a fresh one. To pass installer options, add them after bash -s --:

curl -fsSL https://gardience.com/i/YOUR-CODE | sudo bash -s -- --hostname gardience.example.com --fleet-size 1000

The release is unpacked in /opt/gardience/releases/X.Y.Z (or under --dir). To check the release signature yourself, or for a server without internet access, use the steps below instead.

If something goes wrong#

• Checks come first. Before it changes anything, the installer checks the ports, memory, free disk and any earlier install, and stops with what to do if one is not right. Nothing is installed on a server that fails a check, Docker included.
• Run it again. If an install stops part-way (a dropped connection while it downloads, a reboot), run the same command again: it carries on where it stopped, with the same settings. Downloads are retried three times on their own.
• Host firewall. With firewalld or ufw on, add --open-firewall to open the console and agent ports (the one-command install does this for you). Otherwise the installer finishes and prints the exact commands. Note that Docker publishes its ports beneath ufw, so ufw rules alone do not keep the console off the network.
• Behind a proxy. If HTTPS_PROXY (or https_proxy) is set, the installer gives Docker the same proxy for image downloads, builds and Gardience's own outbound calls. sudo drops proxy settings that live only in your shell: set them in /etc/environment, or run the one-command install with sudo -E bash.
• A proxy that inspects HTTPS (Zscaler, Palo Alto, Blue Coat and the like re-sign every download with your company's own certificate authority). If your IT team already added that authority to the server's trust store (/usr/local/share/ca-certificates on Ubuntu and Debian, /etc/pki/ca-trust/source/anchors on the RHEL family), the installer finds it and Gardience's images and outbound calls trust it too. Otherwise pass the authority's certificate with --ca-cert /path/to/company-ca.pem. A new authority later: run the install again.
• A Salt master already on this server. The installer stops and points you to attach mode, which gives your existing master and its agents Gardience's console.
• Install reports. The one-command install tells gardience.com whether it finished, or the step it stopped at, with your operating system and how long it took: no names, addresses or anything about your machines (they are removed from the step text before it is sent). Add --no-report after bash -s --, or set GARDIENCE_NO_REPORT=1, to turn that off.

Before you start#

• A server that meets the requirements. Docker can be missing: the installer offers to install it (Ubuntu, Debian, RHEL, Rocky, AlmaLinux, Oracle Linux, CentOS Stream, Amazon Linux 2023). If Docker is already there (for example Ubuntu's docker.io), the installer adds only what it lacks: the Compose plugin. It is one file checked against its published checksum. Nothing is built on the server.
• The release bundle gardience-X.Y.Z.tar.gz with its .sha256 and .sha256.sig files.
• Your license file (free at gardience.com/free for up to 10 machines, or a 90-day trial at gardience.com/trial). The install downloads Gardience's images with it, so the server needs to reach gardience.com and gardience-releases.s3.us-east-1.amazonaws.com over HTTPS (directly or through a proxy). No internet at all? Use the offline bundle.

Install#

To install:

1. Copy the bundle and its .sha256 file to the server, then check the download:

   Copy

   sha256sum -c gardience-X.Y.Z.tar.gz.sha256

2. Extract the bundle in a folder where it can stay. The install keeps its release files in this folder and refers to it until your first upgrade, so do not delete it. Do not extract it inside /opt itself, because the bundle unpacks to a folder named gardience and the default install folder is /opt/gardience.

   Copy

   sudo mkdir -p /opt/gardience-release
   sudo tar xzf gardience-X.Y.Z.tar.gz -C /opt/gardience-release
   cd /opt/gardience-release/gardience

3. Optional, but recommended: create a passphrase file for encrypting the automatic pre-upgrade backups. Those backups hold every key. Keep the file readable by root only.

   Copy

   sudo sh -c 'umask 077; openssl rand -base64 32 > /root/.gardience-backup-pass'

4. Run the installer. Set the name agents and browsers will use, your fleet size and your license:

   Copy

   sudo ./install/install.sh \
     --hostname gardience.example.com \
     --fleet-size 1000 \
     --license /path/to/gardience-license.json \
     --backup-passphrase-file /root/.gardience-backup-pass

   The first run downloads Gardience's prebuilt images with your license (about 300 MB) and checks each one against the SHA-256 in the signed release. The installer then starts the services and waits up to 3 minutes for the console to answer.

5. Save the output. It shows:

   • the console address, for example https://gardience.example.com/
   • the admin password. It is shown only once.
   • the address and ports agents should use
   • the management commands

6. Check the install:

   Copy

   sudo /opt/gardience/gardience status
   sudo /opt/gardience/gardience doctor

   status lists the containers and the health result. doctor checks services, the Salt connection, disk space, the TLS certificate, the license, the audit log and backups, and exits with code 1 if any check fails.

The installer refuses to run when:

• Gardience is already installed in the target folder (it finds a .env file there). Manage that install with its gardience command instead.
• Data from an earlier install with the same --name still exists (a Docker volume named NAME_gardiencedata). This stops an old audit log, vault or node keys from being mixed with a new install. The error message shows how to restore that data or remove it.

Installer options#

Run ./install/install.sh --help to print the option list. Every option takes a value except --insecure-salt-api and --upgrade.

Location and web access#

The self-signed certificate is valid for 825 days and covers --hostname, localhost, 127.0.0.1 and the server's own addresses.

Servers on a VPN. The server's address is the one on the network card that reaches the internet, except when the internet goes through a VPN (Tailscale, WireGuard, OpenVPN, a company VPN): then the VPN address would only work inside the VPN, so the installer uses the server's own network address instead and says so. The sign-in details list every address the console answers on. If the VPN also uses Docker's address range (172.17 and up), the server cannot reach its own console while the VPN is on; run the install with the VPN off, or give Docker another range in /etc/docker/daemon.json ("default-address-pools") before installing.

Salt and agents#

License and backups#

Primary and standby pairs#

Use these only when you run two servers, a primary and a warm standby. See Upgrade for how upgrades treat a pair.

Attach mode#

These apply only when you attach to your own Salt master. See Attach to an existing Salt master.

Used by upgrades only#

First sign-in#

To sign in for the first time:

1. Open the console address the installer printed, for example https://gardience.example.com/. With the self-signed certificate your browser shows a warning until you replace the certificate with your own.
2. Sign in as admin with the password from the installer output. If the page asks for a login type, choose file, which is used for the accounts the gardience command creates.

3. Replace the admin password. This creates a new random password and shows it once:

   Copy

   sudo /opt/gardience/gardience user passwd admin

4. Create an account for each person instead of sharing admin. Roles are admin, operator, approver, viewer and helpdesk-windows. Each new password is shown once.

   Copy

   sudo /opt/gardience/gardience user add alice operator

Sessions last 8 hours for local accounts (session_hours in config/users.yaml, 1 to 24) and 1 hour for directory and single sign-on accounts (directory_session_hours), and are shared by every open tab in the browser (closing every console tab ends the shared session after a minute). Removing a user, changing their role or resetting their password ends their open sessions at once, so the change applies at their next sign-in. Sign-ins are rate limited per client address. See Users and roles for what each role can do.

To use your own TLS certificate later, copy the certificate to config/tls/gardience.crt and the key to config/tls/gardience.key in the install folder, then run sudo /opt/gardience/gardience restart.

Licensing#

A license is a small signed file. Gardience checks the signature on the server itself, with no internet connection, so it works on air-gapped networks. A license sets how many nodes you may manage and when it expires.

To install or replace a license, or to see its status:

sudo /opt/gardience/gardience license /path/to/gardience-license.json
sudo /opt/gardience/gardience license

What happens when the license does not cover the fleet:

Once a license has expired, or the fleet has stayed over its limit past the 30 days, security work still runs: installing updates, rebooting to finish them, re-applying the security baseline and checking that machines are back. Salt itself is never affected by the license.

Next steps#

Add machines to the fleet. The installer output already shows the address agents use.

Related#

• Requirements
• Enroll Linux machines
• Enroll Windows machines
• Upgrade