Backend Installation Guide

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.

wget https://storage.googleapis.com/ticrypt/install/ticrypt-setup-0.1.9.tgz
tar -xzf ticrypt-setup-0.1.9.tgz
cd ticrypt-setup
./ticrypt-setup.sh

Before running the installer, review and update the required configuration files as described below.

Architecture Overview

The tiCrypt backend has a modular architecture consisting of 10 services that communicate exclusively via TCP. This design allows services to be deployed on independent machines.

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

System Requirements

Operating system: RHEL 8+ or Rocky Linux 8+ (or compatible distribution) on all backend and worker nodes
Python 3 installed on all target nodes
Ansible installed on the control node (installation guide)
MongoDB installed and accessible from the backend node (see MongoDB Setup)
Nginx installed on the backend node for TLS termination and reverse proxying

Network Requirements

SSH access from the 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, e.g. 8443) accessible from clients
Proxy ports for VM connections must be accessible from the outside. These are defined in the ticrypt-proxy configuration (e.g. 6000–6010) and firewall rules must be coordinated with this setting. See Service Configuration for details.
Port 22 on each VM host must be reserved for the tiCrypt VM Controller

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. If this was not handled by the installer, 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

Quick Start​

Architecture Overview​

Prerequisites​

System Requirements​

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)​