Add docs/LINUX_INSTALLATION.md

docs/LINUX_INSTALLATION.md

@@ -0,0 +1,231 @@
+# 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:
+
+```bash
+cargo build --release
+```
+
+The same testnet build can be requested explicitly:
+
+```bash
+cargo build --release --features testnet
+```
+
+Mainnet has its own feature flag:
+
+```bash
+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:
+
+```text
+target/release/
+```
+
+The testnet node binary is:
+
+```text
+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](src/branch/main/docs/POSTGRES.md).
+
+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:
+
+```bash
+cargo build --release
+```
+
+Run the PostgreSQL installer with root access:
+
+```bash
+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:
+
+```ini
+[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:
+
+```text
+/etc/contractless/settings.ini
+```
+
+Create the config directory:
+
+```bash
+sudo mkdir -p /etc/contractless
+```
+
+Move the repository settings file:
+
+```bash
+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:
+
+```bash
+sudo cp ./target/release/contractless-testnet /usr/bin/
+```
+
+Copy the PostgreSQL installer if you want it available system-wide:
+
+```bash
+sudo cp ./target/release/postgres_installer /usr/bin/
+```
+
+Copy wallet tools:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+contractless-testnet --status
+```
+
+Stop the daemon:
+
+```bash
+contractless-testnet --stop
+```
+
+The Linux daemon PID file is stored under the active network's `DB_PATH`.
+
+## Updating a Node
+
+Stop the node:
+
+```bash
+contractless-testnet --stop
+```
+
+Pull the latest source:
+
+```bash
+git pull
+```
+
+Rebuild:
+
+```bash
+cargo build --release
+```
+
+Copy the updated binary:
+
+```bash
+sudo cp ./target/release/contractless-testnet /usr/bin/
+```
+
+Start the node:
+
+```bash
+contractless-testnet
+```