Contractless/docs/LINUX_INSTALLATION.md

Linux Installation

This guide explains how to build, install, configure, and start a Contractless testnet node on Linux.

Contractless can be run from the build folder, from a user-owned install folder, or from a system path such as /usr/bin. For public testnet nodes, use a stable run path and a stable settings.ini location so runtime data does not move unexpectedly between starts.

Build Flags

The default build target is testnet:

cargo build --release

The same testnet build can be requested explicitly:

cargo build --release --features testnet

Mainnet has its own feature flag:

cargo build --release --no-default-features --features mainnet

Mainnet is not active during the testnet phase. Use the testnet binary unless mainnet has been officially enabled.

After building, release binaries are written to:

target/release/

The testnet node binary is:

target/release/contractless-testnet

PostgreSQL Installation

The installer only supports Linux systems where this apt-get flow is valid. If your Linux distribution does not use apt-get, create the PostgreSQL database manually.

Contractless uses PostgreSQL for transaction lookup and mempool-style records. The node creates and updates its own tables during startup, but PostgreSQL itself must exist first with a database, user, password, and permissions.

Build the release binaries first:

cargo build --release

Run the PostgreSQL installer with root access:

sudo ./target/release/postgres_installer

The Linux installer:

• checks whether psql is installed
• runs apt-get update when PostgreSQL is missing
• installs PostgreSQL with apt-get install -y postgresql
• updates local password authentication in pg_hba.conf when needed
• reloads PostgreSQL
• creates the configured database user
• creates the configured database
• prints the [Postgres] settings block to paste into settings.ini

For testnet builds, paste the printed values into [Postgres-Testnet] in the active settings.ini.

Example:

[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = your_postgres_password_here
dbname = contractless_db

Run Path and Settings Location

The node loads settings.ini in this order:

1. --config <path>
2. SETTINGS_PATH environment variable
3. ./settings.ini
4. settings.ini beside the executable
5. /etc/contractless/settings.ini

For a stable Linux install, use:

/etc/contractless/settings.ini

Create the config directory:

sudo mkdir -p /etc/contractless

Move the repository settings file:

sudo mv ./settings.ini /etc/contractless/settings.ini

The node also scopes runtime folders by network internally, so testnet data and mainnet data do not collide.

Important runtime paths:

Setting	Purpose
BLOCK_PATH	Saved block files
TORRENT_PATH	Torrent metadata and staged torrents
DB_PATH	sled state and Linux PID file
BALANCE_SHEET	Balance files
LOG_PATH	Runtime logs
WALLET_PATH	Wallet directory
WALLET_NAME	Wallet filename

Copy Binaries

Copy the testnet node binary into a system path:

sudo cp ./target/release/contractless-testnet /usr/bin/

Copy the PostgreSQL installer if you want it available system-wide:

sudo cp ./target/release/postgres_installer /usr/bin/

Copy wallet tools:

sudo cp ./target/release/create_new_wallet /usr/bin/
sudo cp ./target/release/recreate_wallet /usr/bin/
sudo cp ./target/release/recreate_wallet_from_image /usr/bin/
sudo cp ./target/release/register_wallet /usr/bin/
sudo cp ./target/release/verify_address /usr/bin/

Copy transaction and lookup tools as needed:

sudo cp ./target/release/create_transfer_tx /usr/bin/
sudo cp ./target/release/broadcast_transaction /usr/bin/
sudo cp ./target/release/lookup_height /usr/bin/
sudo cp ./target/release/lookup_transaction /usr/bin/
sudo cp ./target/release/lookup_remote_balance /usr/bin/

You can copy any additional tools from target/release using the same pattern.

Start the Node

Start the testnet node:

contractless-testnet

On Linux, the node prompts for the wallet decryption key and then detaches into the background by default.

Use a specific settings file:

contractless-testnet --config /etc/contractless/settings.ini

Startup Flags

Linux node flags:

Flag	Purpose
--config <path>	Load a specific settings.ini file
--status	Check whether the daemonized node is running
--stop	Stop the daemonized node

Check daemon status:

contractless-testnet --status

Stop the daemon:

contractless-testnet --stop

The Linux daemon PID file is stored under the active network's DB_PATH.

Updating a Node

Stop the node:

contractless-testnet --stop

Pull the latest source:

git pull

Rebuild:

cargo build --release

Copy the updated binary:

sudo cp ./target/release/contractless-testnet /usr/bin/

Start the node:

contractless-testnet