Backend Installation Guide

Last updated: April 11, 2026Latest Frontend Version: 2.16.8

Pre-Installation Checklist

Complete every item below before running the installer. A misconfigured network, missing DNS record, or invalid TLS certificate will cause installation to fail or produce a non-functional system.

🗄️Hardware — Minimum Requirements

Single server with 32+ CPU cores (virtualization extensions enabled in BIOS)

128 GB+ RAM

2 TB+ disk space

These are minimum specs for a combined backend + VM host node (demo or small production). Production deployments will require more. See the Infrastructure Guide for architecture-specific sizing.

🐧Operating System

RHEL 8/9 or Rocky Linux 8/9 (or compatible RPM-based distribution)

Access to RPM package repositories (internet or local mirror)

Python 3 installed on all target nodes

Ansible installed on the control node

📦Software Dependencies

MongoDB installed and configured as a replica set (see MongoDB Setup)

Nginx installed on the backend node for TLS termination and reverse proxying

🌐Network — Ports

Port 443 open and reachable from user machines — TLS / HTTPS

Ports 6000–6100 open and reachable from user machines — VM connection tunnels

Firewall rules configured to allow the above ports

Port 22 open for SSH management access to the backend serverOptional

VPN configured and testedOptional

📡DNS

A record for ticrypt.example.com — main backend and web interface

A record for audit.example.com — tiCrypt Audit interface

A record for sftp.example.com — SFTP data ingress

A record for mailbox.example.com — URL-based data ingress

All four records must point to the server IP. Replace example.com with your domain.

🔒TLS Certificates

TLS certificate obtained covering all four subdomains (SAN or wildcard)

Certificate and private key files present on the server

Production note: For production deployments, consider issuing a separate certificate for the main backend (ticrypt.example.com) rather than sharing one wildcard or SAN cert across all four subdomains. The sftp and mailbox services are exposed to external parties, making their certificates a higher compromise risk. Isolating the core backend onto its own certificate ensures that a compromised ingress cert cannot be used to impersonate it.

Pre-Installation Testing

Verify DNS, certificates, and port connectivity from the user machines that will connect to the system before running the installer.

✅Test 1 — DNS Resolution

Run from each user machine. Every name must resolve to the server IP:

nslookup ticrypt.example.com
nslookup audit.example.com
nslookup sftp.example.com
nslookup mailbox.example.com

All four names resolve to the correct server IP

✅Test 2 — TLS Certificate

Inspect the certificate on the server using openssl:

openssl x509 -in /path/to/cert.pem -text -noout

Verify the following in the output:

Subject Alternative Names (SANs) list all four subdomains

Certificate is not expired (check Not Before / Not After fields)

Issuing CA is trusted by your organization

✅Test 3 — Port Connectivity

On the server, open a listener. On the client, connect and type any text — it should appear on the server. Ports below 1024 require root.

# server (port 443 requires root)
sudo nc -l 443

# client
nc ticrypt.example.com 443
# or
telnet ticrypt.example.com 443

Repeat for a port in the tunnel range:

# server
nc -l 6000

# client
nc ticrypt.example.com 6000

Port 443 reachable from user machines

Ports 6000–6100 reachable from user machines

Supported Installation Method

ticrypt-setup with Ansible is the only supported and recommended installation method for tiCrypt backends. All other installation approaches are deprecated and unsupported.

Quick Start

The following steps install the tiCrypt backend using the supported Ansible-based automation workflow. Review and update the required configuration files as described in the Configuration section before running ticrypt-setup.sh.

wget https://storage.googleapis.com/ticrypt/install/ticrypt-setup-0.1.9.tgz
tar -xzf ticrypt-setup-0.1.9.tgz
cd ticrypt-setup
# edit inventory.ini and ticrypt.yml before running
./ticrypt-setup.sh

Architecture Overview

The tiCrypt backend has a modular architecture consisting of 10 services that communicate exclusively via TCP. This design allows services to be distributed across independent machines, though a single-server deployment is also supported.

Service	Role
`ticrypt-auth`	Authorization and user management
`ticrypt-rest`	REST API
`ticrypt-file-manager`	File and directory management
`ticrypt-storage`	Encrypted file storage
`ticrypt-vm`	Virtual machine management
`ticrypt-proxy`	VM connection proxy
`ticrypt-logger`	Logging
`ticrypt-stats`	Statistics gathering
`ticrypt-notifications`	Notifications
`ticrypt-maintenance`	Scheduled maintenance tasks

In addition to the backend, the tiCrypt VM Controller Service delivers signed code to virtual machines and is implemented as a set of flat files served by Nginx.

For more details on each service, see the Backend Introduction and Service Configuration pages.

Prerequisites

All items in the Pre-Installation Checklist must be completed. The following additional requirements apply:

Network Requirements

SSH access from the Ansible control node to all target nodes (the Ansible user must have passwordless sudo privileges)
MongoDB port (default 27017) accessible from all backend services
Backend API port (configurable, default 8443) accessible internally — Nginx reverse-proxies external HTTPS traffic on port 443 to this port
Proxy ports for VM connections must be accessible from outside the network. These are defined in the ticrypt-proxy configuration (default 6000–6100) and firewall rules must match. See Service Configuration for details.
Port 22 on each VM host must be reserved for the tiCrypt VM Controller — this is not SSH, but the encrypted tunnel endpoint controlled by ticrypt-vmc

Storage Requirements

Sufficient disk space for the tiCrypt data directory (keys, metadata, encrypted files)
If using Libvirt VMs: a distributed file system shared by all VM hosts, large enough to accommodate VM images, VM drives, and Libvirt temporary files. See Libvirt Realms for details.

Download and Extract

Download the setup archive:

wget https://storage.googleapis.com/ticrypt/install/ticrypt-setup-0.1.9.tgz

Extract the archive and enter the directory:

tar -xzf ticrypt-setup-0.1.9.tgz
cd ticrypt-setup

The extracted directory contains the Ansible playbooks, configuration templates, and the installation script ticrypt-setup.sh.

Configuration

The installer uses two primary configuration files: inventory.ini and ticrypt.yml.

inventory.ini — Node inventory

The inventory.ini file defines the backend and worker nodes targeted by Ansible.

[backend]
backend01 ansible_host=10.0.0.10

[workers]
worker01 ansible_host=10.0.0.20
worker02 ansible_host=10.0.0.21

[all:vars]
ansible_user=ticrypt
ansible_python_interpreter=/usr/bin/python3

Guidance:

Hostnames must be resolvable or mapped using ansible_host
The SSH user must have passwordless sudo privileges
All nodes must be reachable from the control node

ticrypt.yml — Deployment configuration

The ticrypt.yml file defines tiCrypt-specific configuration values used during installation.

deployment_name: ticrypt-prod

backend:
  listen_address: 0.0.0.0
  listen_port: 8443

database:
  host: localhost
  port: 27017
  name: ticrypt

storage:
  data_root: /var/lib/ticrypt
  temp_root: /var/lib/ticrypt/tmp

logging:
  level: INFO
  log_dir: /var/log/ticrypt

Guidance:

Paths must exist or be creatable by the installer
Values are consumed directly by Ansible templates
Changes require re-running ticrypt-setup.sh to take effect

Running the Installer

From the root of the extracted ticrypt-setup directory, run:

./ticrypt-setup.sh

The installer will:

Validate the Ansible environment
Load configuration from inventory.ini and ticrypt.yml
Install required system dependencies
Deploy and configure all 10 backend services
Apply configuration templates
Enable and start tiCrypt services

Post-Installation

Verify Services

After installation completes, confirm that all backend services are running:

systemctl status ticrypt-auth
systemctl status ticrypt-rest
systemctl status ticrypt-file-manager
systemctl status ticrypt-storage
systemctl status ticrypt-vm
systemctl status ticrypt-proxy
systemctl status ticrypt-logger
systemctl status ticrypt-stats
systemctl status ticrypt-notifications
systemctl status ticrypt-maintenance

Review logs under /var/log/ticrypt for any startup errors.

MongoDB Replica Set

tiCrypt requires MongoDB to be configured as a replica set (as noted in the Pre-Installation Checklist). If the replica set was not initialized during MongoDB setup, see MongoDB Setup for instructions on configuring a single-node or multi-node replica set.

TLS Certificates

Nginx must be configured with valid TLS certificates for the tiCrypt backend to serve HTTPS traffic. See Nginx TLS Configuration for the required steps, including certificate verification, Diffie-Hellman parameter generation, and SELinux configuration.

Service Configuration

Each of the 10 backend services has its own configuration file. After installation, you may need to adjust service-specific settings. The two most complex services to configure are:

ticrypt-auth — handles authentication, MFA, key escrow, and split credentials. See Auth Service (ticrypt-auth).
ticrypt-vm — manages Libvirt realms, hardware profiles, and cost functions. See Libvirt Realms.

For all other services, see Service Configuration.

Connectivity Check

Verify worker nodes are registered and reachable from the backend
Validate connectivity using the tiCrypt frontend or the REST API

Manual Installation

Manual installation of tiCrypt backend components is possible but not recommended. Manual workflows increase deployment complexity, introduce configuration drift, and are not the supported installation path for production environments.

Reference Configuration Files (Complete Examples)

These reference files are provided as complete, copy-paste-ready examples. Update values to match your environment before running ticrypt-setup.sh.

inventory.ini (complete reference)

# -----------------------------------------------------------------------------
# tiCrypt Ansible Inventory
#
# - Define backend nodes in [backend]
# - Define worker nodes in [workers]
# - Provide common SSH settings in [all:vars]
#
# Notes:
# - Use hostnames if DNS is in place; otherwise set ansible_host=<ip>
# - The ansible_user must be able to sudo without being prompted for a password
# - Ensure Python 3 exists on each target node and set ansible_python_interpreter
# -----------------------------------------------------------------------------

[backend]
# Primary backend node (API/services, database, etc., depending on your playbooks)
backend01 ansible_host=10.0.0.10

[workers]
# Worker nodes used for compute / job execution / services as defined by your roles
worker01 ansible_host=10.0.0.20
worker02 ansible_host=10.0.0.21

[all:vars]
# SSH user used by Ansible to connect to all nodes above
ansible_user=ticrypt

# Path to Python on the target nodes (required for Ansible modules)
ansible_python_interpreter=/usr/bin/python3

# Optional: if your environment requires privilege escalation
# ansible_become=true
# ansible_become_method=sudo

# Optional: if you use SSH keys in a non-default location
# ansible_ssh_private_key_file=~/.ssh/id_rsa

# Optional: if your SSH daemon uses a non-standard port
# ansible_port=22

ticrypt.yml (complete reference)

# -----------------------------------------------------------------------------
# tiCrypt Deployment Configuration
#
# This file provides deployment-specific values consumed by Ansible templates
# and roles during installation. Update values to match your environment.
#
# Guidance:
# - Use fully qualified hostnames where appropriate
# - Ensure all paths are valid and writable by the installed services
# - If you change this file after installation, re-run ticrypt-setup.sh
# -----------------------------------------------------------------------------

# A short identifier used in logs, tags, and generated artifacts
deployment_name: ticrypt-prod

# -----------------------------------------------------------------------------
# Backend service configuration
# -----------------------------------------------------------------------------
backend:
  # Address the backend binds to. 0.0.0.0 listens on all interfaces.
  listen_address: 0.0.0.0

  # Public/service port for the backend API (adjust to match your environment)
  listen_port: 8443

  # Optional: external hostname clients use to reach the backend
  # public_hostname: ticrypt.example.edu

  # Optional: if TLS termination is handled elsewhere, document that here
  # tls_terminated_upstream: false

# -----------------------------------------------------------------------------
# Database configuration (MongoDB)
# -----------------------------------------------------------------------------
database:
  # Database host. Use localhost if MongoDB is colocated with the backend.
  host: localhost

  # Database port
  port: 27017

  # Database name
  name: ticrypt

  # Optional: credentials if required by your deployment
  # username: ticrypt
  # password: change-me

  # Optional: replica set or connection options
  # options: "replicaSet=rs0&authSource=admin"

# -----------------------------------------------------------------------------
# Storage paths
# -----------------------------------------------------------------------------
storage:
  # Root directory for persistent tiCrypt data (keys, metadata, etc.)
  data_root: /var/lib/ticrypt

  # Temporary working directory for installers, staging, and intermediate files
  temp_root: /var/lib/ticrypt/tmp

  # Optional: additional mounts/paths used in your deployment
  # inbox_root: /var/lib/ticrypt/inboxes
  # drives_root: /var/lib/ticrypt/drives

# -----------------------------------------------------------------------------
# Logging configuration
# -----------------------------------------------------------------------------
logging:
  # Log level (common values: DEBUG, INFO, WARNING, ERROR)
  level: INFO

  # Directory where logs are written
  log_dir: /var/log/ticrypt

  # Optional: log rotation behavior if your roles support it
  # rotate: true
  # max_size_mb: 100
  # max_files: 10

# -----------------------------------------------------------------------------
# Optional: integrations / feature flags (uncomment if your roles support these)
# -----------------------------------------------------------------------------
# integrations:
#   slurm:
#     enabled: false
#     # controller_host: slurmctld.example.edu
#     # rest_api_url: https://slurmrest.example.edu
#
# security:
#   # Whether to enforce hardened defaults (depends on role support)
#   hardened_defaults: true
#
# networking:
#   # If your environment requires explicit interface binding
#   # interface: eth0

Pre-Installation Checklist​

Pre-Installation Testing​

Quick Start​

Architecture Overview​

Prerequisites​

Network Requirements​

Storage Requirements​

Download and Extract​

Configuration​

Running the Installer​

Post-Installation​

Verify Services​

MongoDB Replica Set​

TLS Certificates​

Service Configuration​

Connectivity Check​

Manual Installation​

Reference Configuration Files (Complete Examples)​