From 4c5f1486b352c5f3b70eac1b32c649a3d5ec45b6 Mon Sep 17 00:00:00 2001 From: contractless Date: Sun, 12 Jul 2026 16:07:40 +0000 Subject: [PATCH] Add docs/WINDOWS_INSTALLATION.md --- docs/WINDOWS_INSTALLATION.md | 282 +++++++++++++++++++++++++++++++++++ 1 file changed, 282 insertions(+) create mode 100644 docs/WINDOWS_INSTALLATION.md diff --git a/docs/WINDOWS_INSTALLATION.md b/docs/WINDOWS_INSTALLATION.md new file mode 100644 index 0000000..56993ce --- /dev/null +++ b/docs/WINDOWS_INSTALLATION.md @@ -0,0 +1,282 @@ +# Windows Installation + +This guide explains how to build, install, configure, and run a Contractless testnet node as a Windows service. + +Windows service commands should be run from an elevated PowerShell window. The service runs in the background and must be unlocked with `contractless-submit-key.exe` after it starts. + +## Build Flags + +The default build target is testnet: + +```powershell +cargo build --release +``` + +The same testnet build can be requested explicitly: + +```powershell +cargo build --release --features testnet +``` + +Mainnet has its own feature flag: + +```powershell +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.exe +``` + +The Windows service unlock helper is: + +```text +target\release\contractless-submit-key.exe +``` + +## PostgreSQL Installation + +The Windows PostgreSQL installer requires an elevated terminal. If you prefer to create PostgreSQL manually, [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: + +```powershell +cargo build --release +``` + +Run the PostgreSQL installer from an elevated PowerShell window: + +```powershell +.\target\release\postgres_installer.exe +``` + +The Windows installer: + +- checks whether PostgreSQL already exists at the selected install path +- downloads the PostgreSQL installer when needed +- installs PostgreSQL unattended +- creates or updates the configured database user +- creates the configured database when it does not already exist +- verifies the blockchain database login +- prints the `[Postgres]` and `[Postgres-Testnet]` settings blocks 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 ` +2. `SETTINGS_PATH` environment variable +3. `.\settings.ini` +4. `settings.ini` beside the executable + +For a stable Windows service install, use: + +```text +C:\Program Files\Contractless\settings.ini +``` + +Create the install directory from an elevated PowerShell window: + +```powershell +New-Item -ItemType Directory -Force "C:\Program Files\Contractless" +``` + +Move the repository settings file into the install directory: + +```powershell +Move-Item .\settings.ini "C:\Program Files\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 | +| `BALANCE_SHEET` | Balance files | +| `LOG_PATH` | Runtime logs | +| `WALLET_PATH` | Wallet directory | +| `WALLET_NAME` | Wallet filename | + +## Copy Binaries + +Copy the testnet node binary and Windows unlock helper into the install directory: + +```powershell +Copy-Item .\target\release\contractless-testnet.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\contractless-submit-key.exe "C:\Program Files\Contractless\" +``` + +Copy the PostgreSQL installer if you want it available from the install directory: + +```powershell +Copy-Item .\target\release\postgres_installer.exe "C:\Program Files\Contractless\" +``` + +Copy wallet tools: + +```powershell +Copy-Item .\target\release\create_new_wallet.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\recreate_wallet.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\recreate_wallet_from_image.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\register_wallet.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\verify_address.exe "C:\Program Files\Contractless\" +``` + +Copy transaction and lookup tools as needed: + +```powershell +Copy-Item .\target\release\create_transfer_tx.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\broadcast_transaction.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\lookup_height.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\lookup_transaction.exe "C:\Program Files\Contractless\" +Copy-Item .\target\release\lookup_remote_balance.exe "C:\Program Files\Contractless\" +``` + +You can copy any additional tools from `target\release` using the same pattern. + +## Install the Service + +Install the Windows service from an elevated PowerShell window: + +```powershell +& "C:\Program Files\Contractless\contractless-testnet.exe" --install-service +``` + +This command is only needed the first time the service is installed. Do not run `--install-service` every time you restart the node, rebuild from source, or copy in a newer binary. + +The service is installed using the binary path where `contractless-testnet.exe` is located when `--install-service` is run. If you later move the binary to a different folder, uninstall and reinstall the service from the new path. + +## Start and Unlock the Service + +Start the service: + +```powershell +& "C:\Program Files\Contractless\contractless-testnet.exe" --start-service +``` + +After the service starts, submit the wallet decryption key: + +```powershell +& "C:\Program Files\Contractless\contractless-submit-key.exe" +``` + +The service starts in a locked state. It does not begin normal unlocked node operation until `contractless-submit-key.exe` accepts the wallet key. + +Check the unlock pipe: + +```powershell +& "C:\Program Files\Contractless\contractless-submit-key.exe" ping +``` + +Check the service unlock state: + +```powershell +& "C:\Program Files\Contractless\contractless-submit-key.exe" status +``` + +## Stop the Service + +Stop the service from an elevated PowerShell window: + +```powershell +& "C:\Program Files\Contractless\contractless-testnet.exe" --stop-service +``` + +## Automatic Startup + +The service can be configured to start automatically with Windows. + +From an elevated PowerShell window: + +```powershell +sc.exe config ContractlessTestnet start= auto +``` + +Or use Windows Services: + +1. Open `services.msc` +2. Find `Contractless Testnet` +3. Open Properties +4. Set Startup type to `Automatic` + +If the service is set to start automatically, you do not need to run `--start-service` after every reboot. You still need to run `contractless-submit-key.exe` after the computer restarts because the service cannot unlock the wallet without the wallet decryption key. + +## Updating a Node + +For normal source updates, do not reinstall the service. + +Stop the service: + +```powershell +& "C:\Program Files\Contractless\contractless-testnet.exe" --stop-service +``` + +Pull the latest source: + +```powershell +git pull +``` + +Rebuild: + +```powershell +cargo build --release +``` + +Copy the updated binaries: + +```powershell +Copy-Item .\target\release\contractless-testnet.exe "C:\Program Files\Contractless\" -Force +Copy-Item .\target\release\contractless-submit-key.exe "C:\Program Files\Contractless\" -Force +``` + +Start the service: + +```powershell +& "C:\Program Files\Contractless\contractless-testnet.exe" --start-service +``` + +Submit the wallet decryption key: + +```powershell +& "C:\Program Files\Contractless\contractless-submit-key.exe" +``` + +## Uninstall the Service + +Uninstall the service only when you want to remove the Windows service registration: + +```powershell +& "C:\Program Files\Contractless\contractless-testnet.exe" --uninstall-service +``` + +Uninstalling is not part of normal updates.