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

Do not expose PostgreSQL to the public Internet. The PostgreSQL port should not be publicly accessible. Contractless needs a public RPC port for peers, but PostgreSQL should stay local or private, usually on 127.0.0.1. Do not open PostgreSQL port 5432 in your router, cloud firewall, VPS firewall, or host firewall.

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