From c23405cc8a3d17fa0c92eed07bff8da000f8b00b Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Sat, 7 Nov 2026 08:42:32 +0100 Subject: [PATCH 1/3] docs: quick-start guide (Docker and native, pruned and full) docs/quick-start.md: a short guide to run a community node on mainnet, with Docker or the native package (Linux in tmux with the systemd unit, Windows, macOS), pruned on lmdb or full on rocksdb from the published snapshot with snapshot serving on. Requirements, ports, the set-up answers per profile, first checks, the wallet, upgrading with the database kept and common problems. Linked from the top of the README. Co-Authored-By: Claude Opus 5.5 --- README.md | 4 + docs/quick-start.md | 310 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 314 insertions(+) create mode 100644 docs/quick-start.md diff --git a/README.md b/README.md index 2ea38da9d..072a6ab8d 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,10 @@ [![AGPL License](https://img.shields.io/github/license/CREDITSCOM/node.svg?color=green&label=License&style=plastic)](LICENSE) [![Twitter](https://img.shields.io/twitter/follow/creditscom.svg?label=Follow&style=social)](https://twitter.com/intent/follow?screen_name=creditscom) # Credits Node (community) + +> **New here? Start with the [quick-start guide](docs/quick-start.md):** a node running in +> minutes, with Docker or the native package, pruned or full. + The node is the program that runs on the operator's machine and takes part in the CREDITS network. Written in C++. diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 000000000..f12052f6c --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,310 @@ +# Quick start: run a Credits node + +A short, practical guide to get a community node running on mainnet. Pick one route +(Docker or the native package) and one profile (pruned or full), then follow the steps. + +For the details behind each step, see [storage.md](storage.md), [snapshots.md](snapshots.md) and +[packaging/docker/README.md](../packaging/docker/README.md). + +## 1. Pick a profile + +| | Pruned node (recommended) | Full node | +|---|---|---| +| What it keeps | Only recent blocks | Every block since block 0 | +| Good for | Running a node and taking part in the network | Full history: explorers, wallet histories from the start | +| Database | `lmdb` | `rocksdb` (the smallest for a full node) | +| First start | Minutes, from the published snapshot | Minutes from the snapshot, then the older blocks download in the background for about 2 to 3 days | + +Words used below: + +- **Snapshot**: a signed copy of the chain state at a recent block. The node checks it and starts + from it, instead of syncing from block 0 (about 35 hours). +- **Serving snapshots** (`serve=on`): your node shares its own snapshots with new nodes, so they can + start fast too. It uses at most 2 MB/s of upload and about 200 MB of disk. Please leave it on. +- **Backfill**: a full node started from a snapshot fetches the older blocks from other nodes, down + to block 0, while it already runs normally. It can be turned off. + +## 2. Requirements + +| | Pruned node | Full node | +|---|---|---| +| CPU | 2 cores | 4 cores or more (the backfill checks signatures on several threads) | +| Memory | 4 GB (8 GB recommended) | 8 GB | +| Disk | about 10 GB | about 250 to 300 GB with RocksDB (400 GB or more with LMDB or BerkeleyDB); an SSD | +| Network | 3 Mbit/s | 5 Mbit/s or more | + +Systems: Linux x86-64, Windows 10 or later (x64), macOS on Apple Silicon, or any system with Docker. + +**Ports:** + +| Port | Must be | What | +|---|---|---| +| 9510 TCP and UDP | **open** to the internet (firewall and router) | p2p: the other nodes reach yours here | +| 9090 | **closed** to other hosts (localhost only) | the node's API, used by the wallet | +| 9088 | **closed** to other hosts | the diagnostic API (off unless you turn it on) | +| 9080, 9070 | **closed** to other hosts | the smart-contract executor | + +The node listens on 9090 and 9088 on every interface: block them in the firewall. Docker publishes +9090 on `127.0.0.1` only. + +## 3. Docker (any system with Docker) + +1. Download the compose file and the settings file: + + ```sh + mkdir credits && cd credits + curl -fsSLO https://raw.githubusercontent.com/CreditsCommunity/node/master/packaging/docker/docker-compose.yml + curl -fsSL -o .env https://raw.githubusercontent.com/CreditsCommunity/node/master/packaging/docker/.env.example + ``` + +2. Edit `.env` for your profile. + + **Pruned** (the defaults already do this): + + ```ini + CREDITS_STORAGE=pruned + CREDITS_SNAPSHOT=github + CREDITS_SERVE_SNAPSHOT=on + CREDITS_API=on + ``` + + **Full:** + + ```ini + CREDITS_STORAGE=full + CREDITS_DB_BACKEND=rocksdb + CREDITS_SNAPSHOT=github + CREDITS_SERVE_SNAPSHOT=on + CREDITS_API=on + # CREDITS_BACKFILL=off # uncomment to keep only the snapshot's blocks + ``` + + Set `CREDITS_DB_BACKEND=rocksdb` for a full node: without it the full default is `berkeleydb`, + which cannot start from a snapshot and syncs from block 0. `CREDITS_API=on` is needed by the + wallet. For a full node, also raise or remove `cpus: 1.5` and `mem_limit: 4g` in + `docker-compose.yml`. + + `.env` is read on the **first start only**, to write `~/.credits/config.ini`. After that, edit + `config.ini`. + +3. Make the data folder writable by the container (it runs as uid 1000), then start: + + ```sh + mkdir -p ~/.credits && sudo chown -R 1000 ~/.credits + docker compose up -d + docker compose logs -f # Ctrl+C leaves the logs, the node keeps running + ``` + +4. **Back up `~/.credits/keys/`** (the node's identity) and `~/.credits/wallet/` if you use the + wallet. + +Everyday commands: + +| Task | Command | +|---|---| +| Logs | `docker compose logs -f` | +| Stop | `docker compose stop` (it waits up to 120 s, so the node saves its state) or `docker stop -t 120 credits-node` | +| Start again | `docker compose up -d` | +| Upgrade | `docker compose pull && docker compose up -d` (data, `config.ini` and keys stay) | +| Wallet status | `docker compose exec node credits-wallet status` | +| Start over | set `CREDITS_RESET=1` once in `.env` (old data is moved to `~/.credits/old-`), then remove it | + +The data lives in `~/.credits` (`CREDITS_HOME` in `.env`): `config.ini`, `keys/`, `db/`, +`caches/`, `qs/`, `log/`, `wallet/`. + +Never stop the container with the default `docker stop` (10 seconds): it is too short to save the +caches. + +## 4. Native on Linux + +### Download and check + +1. Open the [latest release](https://github.com/CreditsCommunity/node/releases/latest) and download + the Linux package and `SHA256SUMS`: + - `credits-node-4.2.532-community.17-linux-x64.tar.gz` for Ubuntu 24.04, Debian 13 and later + (glibc 2.38); + - `credits-node-4.2.532-community.17-linux-x64-glibc2.31.tar.gz` for Ubuntu 20.04, Debian 11 + and later. + +2. Check and extract: + + ```sh + sha256sum -c --ignore-missing SHA256SUMS # must print "OK" + tar -xzf credits-node-4.2.532-community.17-linux-x64.tar.gz + cd csnode + ``` + +Run everything as a normal user, not as root. + +### Set up and start in tmux + +`tmux` keeps the node running after you close the SSH session (`sudo apt install tmux` if missing). +The set-up can start the node at the end, so run it inside tmux: + +```sh +tmux new -s credits +./setup.sh +``` + +The set-up asks a few questions. Enter keeps the default shown in brackets. + +| # | Question | Pruned | Full | +|---|---|---|---| +| 1 | Pruned or full node? | `pruned` | `full` | +| 2 | Database? | `lmdb` (default) | `rocksdb` (the default is `berkeleydb`: change it) | +| 3 | How should the node get the chain? | `github` (default) | `github` (default) | +| 3b | Fetch the older blocks? (full only) | not asked | `yes` (default); `no` keeps only the snapshot's blocks | +| 4 | Share snapshots with other nodes? | `yes` (default) | `yes` (default) | +| 5 | Which executor? | `community` (default with this package) | `community` | +| 6 | The wallet's account? | `node` (default): the node's own key | `node` | +| 7 | Keep a token cache? | `no` (default), or `yes` to see every token in the wallet | same | +| 8 | Start the node when the set-up is done? | `yes` | `yes` | + +Then it shows a summary and asks `Write config.ini?`: answer `yes`. With `github` it downloads and +checks the snapshot (a few minutes), and starts the node in the same window. + +If the set-up creates the node's key from a 24-word phrase, **write the words on paper**. + +**Detach and reattach:** + +- leave the node running: press `Ctrl+B`, then `D`; +- come back later: `tmux attach -t credits`. + +**Start it again later** (in tmux, in the `csnode` folder): + +```sh +./node --config-file config.ini +``` + +**Stop it cleanly:** press `Ctrl+C` **once** and wait until the prompt comes back. Saving the +caches can take a minute. Do not press it again, and do not kill the process or close the tmux +window meanwhile. + +### Optional: run it as a systemd service + +The Linux package has `credits-node.service`. It runs the node at boot and restarts it on failure. + +1. Stop the node if it runs in tmux. +2. Copy the unit and edit it: + + ```sh + sudo cp credits-node.service /etc/systemd/system/ + sudo nano /etc/systemd/system/credits-node.service + ``` + + Set `User=` to your user, and put the full path of your `csnode` folder in `WorkingDirectory=` + and `ExecStart=`. +3. Enable and start it: + + ```sh + sudo systemctl daemon-reload && sudo systemctl enable --now credits-node + journalctl -u credits-node -f # console output + sudo systemctl stop credits-node # clean stop (it waits up to 5 minutes) + ``` + +The node's own log is in `csnode/log/`. + +## 5. Native on Windows + +1. Download `credits-node-4.2.532-community.17-windows-x64.zip` and `SHA256SUMS-windows-macos` + from the [latest release](https://github.com/CreditsCommunity/node/releases/latest). Check it in + PowerShell and compare with the file: + + ```powershell + Get-FileHash credits-node-4.2.532-community.17-windows-x64.zip + ``` + +2. Extract the zip, for example to `C:\credits`. Open the `csnode` folder. +3. **Double-click `setup.bat`.** It runs `setup.ps1` for you (no change to the PowerShell execution + policy is needed). Answer the questions as in the [Linux table](#set-up-and-start-in-tmux). +4. At the end the node starts in the same window. **Keep that window open**: closing it stops the + node. +5. To start it again later, open `cmd` or PowerShell in the `csnode` folder: + + ```bat + node.exe --config-file config.ini + ``` + +6. To stop it, press `Ctrl+C` once and wait until it exits. + +The package has no Windows service. Run the node in a console window you keep open. + +## 6. macOS (Apple Silicon) + +Download `credits-node-4.2.532-community.17-macos-arm64.tar.gz`, check it with +`shasum -a 256 -c --ignore-missing SHA256SUMS-windows-macos`, extract it, then clear the +download quarantine once (the binaries are not signed) and follow the Linux steps: + +```sh +tar -xzf credits-node-4.2.532-community.17-macos-arm64.tar.gz +xattr -dr com.apple.quarantine csnode +cd csnode && ./setup.sh +``` + +## 7. First checks + +In the console or the log (`csnode/log/`, or `docker compose logs -f`), look for: + +1. The banner with the version and your settings: + + ``` + node 4.2.532-community.17 (protocol 532, build ...) + storage: pruned, lmdb snapshots: serve on + ``` + +2. `checkpoint loaded` and `Storage: quick start`: the node started from the snapshot. +3. The status lines: the round number (`R-...`) and `Last written sequence = ...` grow every few + seconds. A full node with backfill also shows `, oldest stored = ...`, which goes down. +4. A full node logs `BACKFILL: full node with blocks N..M: fetching 0..N-1`, a line every 100,000 + blocks, and at the end `BACKFILL: full history stored`. + +Then ask the node with the wallet, in the `csnode` folder: + +```sh +./credits-wallet --config wallet.toml status +``` + +It shows the network, the last block and `synced`. Wait for `synced: yes` before sending anything. + +## 8. The wallet in two lines + +Open it with `./credits-wallet --config wallet.toml` in `csnode` (`credits-wallet.exe` on Windows; +`docker compose exec node credits-wallet` in Docker). The node's own key is the account `node`: +it receives the node's rewards and delegations; keep savings in a separate account. + +Full guide: `wallet-guide.md` in the package, or +[docs/guide.md](https://github.com/CreditsCommunity/wallet/blob/main/docs/guide.md). On mainnet +every transfer is real. + +## 9. Upgrading and keeping the database + +Docker: `docker compose pull && docker compose up -d`. Native: + +1. **Stop the node cleanly**: `Ctrl+C` once and wait for the prompt, or + `sudo systemctl stop credits-node`. +2. **Extract** the new package into a **new** folder. +3. **Copy** from the old `csnode` folder into the new one: `db/`, `caches/`, `qs/`, + `NodePrivate.txt`, `NodePublic.txt`, `config.ini` (and `known_hosts.txt` if you edited it). +4. **Run the set-up** in the new folder and give the **same storage answers** as before: pruned or + full, and the same database. The node must open the database with the backend that wrote it. +5. **Start the node.** The log shows the new version, then `checkpoint loaded` and + `Storage: quick start`, and the node carries on from its last block. + +Never run the old and the new node at the same time with the same key or the same `db/` folder. + +## 10. Troubleshooting + +| Problem | What to do | +|---|---| +| Few or no neighbours, the node never syncs | Port 9510 (TCP and UDP) is not reachable: open it in the firewall and forward it on the router. | +| Docker: permission denied on `/data`, or the wallet ignores the node's key | The container runs as uid 1000: `sudo chown -R 1000 ~/.credits`, and keep `keys/NodePrivate.txt` at mode 600. | +| The node runs but no smart contract executes | The executor build is outside `executor_commit_min..executor_commit_max` in `config.ini`. Run the set-up again, or set `executor_commit_max=1558` or higher. Copying only the node binary keeps the old executor. | +| `the block database is X, config.ini asks for Y` (exit code 3) | `config.ini` names another database than the one in `db/`. Set `db_backend` back to X, or convert on purpose with `./node --convert-db` (Docker: `CREDITS_CONVERT_DB=yes`). See [storage.md](storage.md#conversion). | +| Snapshot download stopped | Run it again: `./node --download-snapshot` (node stopped) resumes, or run the set-up again. | +| The node stops with exit code 4, `snapshot.mismatch` exists | The restored state did not match the snapshot. Start over with an empty `db/`, `caches/` and `qs/` (Docker: `CREDITS_RESET=1` once). | +| Disk full | A full node needs 250 to 300 GB with RocksDB. Free space or move to a bigger disk, or turn the backfill off (`backfill=off` in `[storage]`, `CREDITS_BACKFILL=off` in Docker before the first start). | +| Linux: `GLIBC_2.38 not found` | Use the `linux-x64-glibc2.31` package. | +| macOS: "cannot be opened" | `xattr -dr com.apple.quarantine csnode` | + +Help: [issues](https://github.com/CreditsCommunity/node/issues) or the +[technical Telegram](https://t.me/creditstechnical). Never share your 24 words or `NodePrivate.txt`. From abcbe0737459f91bddab14857bc8e672aa99c262 Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Sat, 7 Nov 2026 08:42:48 +0100 Subject: [PATCH 2/3] docs: CHANGES row for #172 Co-Authored-By: Claude Opus 5.5 --- docs/CHANGES.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/CHANGES.md b/docs/CHANGES.md index 34e9adf81..e911aeabf 100644 --- a/docs/CHANGES.md +++ b/docs/CHANGES.md @@ -42,7 +42,9 @@ lines under the new release. ## Not released yet -Nothing yet. +| PR | Change | +|---|---| +| #172 | docs: `docs/quick-start.md`, a short quick-start guide (Docker and native Linux, Windows and macOS; pruned on lmdb or full on rocksdb from the snapshot, snapshot serving on; requirements, ports, first checks, the wallet, upgrading with the database kept, common problems), linked from the top of the README | ## community.17 — 2026-11-05 From db6c35b95edaf33c22a8003cac4c0af4fd907598 Mon Sep 17 00:00:00 2001 From: EnzinoBB Date: Sat, 7 Nov 2026 08:57:05 +0100 Subject: [PATCH 3/3] docs: quick-start: the diag port is on by default in the packages Co-Authored-By: Claude Opus 5.5 --- docs/quick-start.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/quick-start.md b/docs/quick-start.md index f12052f6c..f7c68c0f9 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -41,7 +41,7 @@ Systems: Linux x86-64, Windows 10 or later (x64), macOS on Apple Silicon, or any |---|---|---| | 9510 TCP and UDP | **open** to the internet (firewall and router) | p2p: the other nodes reach yours here | | 9090 | **closed** to other hosts (localhost only) | the node's API, used by the wallet | -| 9088 | **closed** to other hosts | the diagnostic API (off unless you turn it on) | +| 9088 | **closed** to other hosts | the diagnostic API (on by default in the packages: the wallet uses it to check the network) | | 9080, 9070 | **closed** to other hosts | the smart-contract executor | The node listens on 9090 and 9088 on every interface: block them in the firewall. Docker publishes