Keycyte PAM 3.2 · Deployment Guide

Running the Installer

The installer install.sh installs Keycyte PAM on the host from the prepared installation package. It is a bash script and must be run with sudo from the package folder.

Before You Begin

• Prepare the installation package as described in Preparing the Installation Package.
• Know the IP address of the primary DNS server that the containers will use, and optionally of a secondary DNS server.

Installer Options

What the Installer Does

The installer runs the following steps:

1. Prerequisites. Checks that Docker is installed, that the Docker daemon is running and accessible, and that Docker Compose is available. Checks that keycyte-pam.tar.gz, docker-compose.yml and .env are in the package folder.
2. Images. Extracts keycyte-pam.tar.gz and loads every image in it with docker load. Then checks that the images keycyte-pam:latest, keycyte-ssh-proxy:latest, keycyte-password-manager:latest, keycyte-radius-server:latest and guacamole/guacd:latest exist. The check also runs with --skip-load.
3. DNS. Asks for the primary and secondary DNS servers and writes them to .env (PRIMARY_DNS, SECONDARY_DNS).
4. Docker group. Finds the group ID of the host’s docker group and writes it to .env (DOCKER_GID), so that the PAM server can read the Docker socket.
5. Host directories. Creates ~/keycyte, ~/drive and ~/record in the home directory of the user who ran sudo, makes that user their owner, and writes the paths and the user and group IDs to .env (KEYCYTE_BASE, KEYCYTE_DRIVE, KEYCYTE_RECORD, RUN_UID, RUN_GID). The containers run with this user and group ID.
6. Certificates. Copies localhost.p12, cacerts.pem and keycyte-ca.crt (those that exist) to ~/keycyte. Warns if localhost.p12 or cacerts.pem is missing.
7. Database check. If .env points to an external database server by IP address, checks that its port is reachable.
8. Start. Starts all containers with docker compose up -d, waits a few seconds, shows the container status and the last log lines of any container that is not running.
9. Master account. Waits until PostgreSQL is ready and the PAM server has created the database schema, then runs initdb/10-master-user.sql to create the master account. If the account already exists, it is left unchanged.

Running the Installer

To run the installer:

1. Open a shell on the host and go to the installation package folder.

2. Run the installer:

   sudo ./install.sh

   To set the DNS server without prompts:

   sudo ./install.sh --dns 10.0.0.53

3. When prompted, enter the IP address of the primary DNS server, and press Enter.

   The prompt shows the current value from .env in brackets. Press Enter without typing to keep it. The installer accepts only an IPv4 address and asks again if the value is not valid.

4. When prompted, enter the IP address of the secondary DNS server, or press Enter to skip it.

   If you skip it, the secondary DNS server is set to the primary one.

5. Wait until the installer finishes.

   The installer prints the status of every container. If all containers run, it prints a message that the installation is complete and all services are up. It then applies the master account script and prints the commands for viewing logs and stopping the services.

Keycyte PAM is installed. Continue with Signing In for the First Time.

Checking the Installation

To check the containers after installation, run the following command in the package folder:

sudo docker compose --env-file .env -f docker-compose.yml ps

All containers (pam, ssh-proxy, guacd, password-manager, radius, postgres-db) should be in the running state.

To follow the PAM server log:

sudo docker compose --env-file .env -f docker-compose.yml logs -f pam

If the Master Account Was Not Created

If PostgreSQL or the database schema was not ready in time, the installer skips the master account script and prints a warning with the command to run. In that case, wait until the PAM server has started, then run the script manually in the package folder:

sudo docker exec -i postgres-db psql -U <db-user> -d <db-name> < initdb/10-master-user.sql

Use the database user and database name from .env (DB_USER, DB_NAME). The installer prints the command with these values filled in.

Running the Installer Again

You can run the installer again, for example after you add a missing certificate file. The installer updates the values it manages in .env and leaves existing directories and the existing master account unchanged. Use --skip-load if the images are already loaded.

sudo docker compose --env-file .env -f docker-compose.yml restart pam

Stopping the Services

To stop and remove the containers, run in the package folder:

sudo docker compose --env-file .env -f docker-compose.yml down

The database volume and the host directories are kept. Run sudo docker compose --env-file .env -f docker-compose.yml up -d to start the services again.