Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ lines under the new release.
|---|---|
| #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 |
| #173 | packaging: a new full node defaults to rocksdb (it starts from a snapshot) in Docker and in the guided set-up (setup.sh, setup.ps1); pruned stays on lmdb; existing installs keep their backend (the database in `db/`, the `db_backend` of `config.ini`, berkeleydb for a full `[storage]` without one; the entrypoint also detects the database of a data folder whose `config.ini` was removed); `docker-compose.yml` takes its limits from `CREDITS_CPUS` (1.5) and `CREDITS_MEMORY` (4g) in `.env` (a full node: 4 and 8g); texts aligned: a full node on rocksdb about 250 to 300 GB, backfill about 2 to 3 days, glibc 2.38 for `linux-x64` (2.31 for `-glibc2.31`) in the README, the image `ghcr.io/creditscommunity/credits-node`, the `config.pruned.ini` comment on the snapshot start; quick-start, storage.md and the Docker README updated; ci: setup-test and the Docker entrypoint test check the rocksdb default and that a full berkeleydb install is kept |
| #174 | docs: quick-start: using an existing node key, plain or encrypted, in Docker or native (a section with copy-paste steps; an encrypted key converted once to plain with the node's own `--dumpkeys`, for Docker and systemd) |

## community.17 — 2026-11-05

Expand Down
152 changes: 151 additions & 1 deletion docs/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -295,7 +295,157 @@ Docker: `docker compose pull && docker compose up -d`. Native:

Never run the old and the new node at the same time with the same key or the same `db/` folder.

## 10. Troubleshooting
## 10. Using your existing node key

Your node's identity is its key: `NodePrivate.txt` and `NodePublic.txt`. To keep an identity you
already have, give the node those two files instead of letting it make new ones. First check which
kind of `NodePrivate.txt` you have:

```sh
wc -c NodePrivate.txt # about 88 characters: plain; about 120: encrypted with a password
```

A **plain** key works everywhere. A key **encrypted by the node** (`--encryptkey`, or the password
choice at its first start) makes the node ask for the password at every start, on its console.

Before you start:

- **Never run two nodes with the same key**, not even for a moment. Stop the old node first.
- **Keep an offline backup** (USB stick, paper) of the original files. A plain key is as exposed
as the machine it is on.
- The wallet uses a plain node key as the account `node` without a password. On mainnet it still
asks you to type `send` before every transfer.

### Native, plain key

Put `NodePrivate.txt` and `NodePublic.txt` in the `csnode` folder **before** you run `./setup.sh`
(`setup.bat` on Windows). The set-up finds them, offers the key as the wallet's account `node`
(answer `node`), and sets `NodePrivate.txt` to mode 600.

### Native, encrypted key

Same place, same set-up. At every start the node asks:

```
The key file seems to be encrypted
To use password for encrytion/decryption press "p", to use file press "f": p
Enter password: ********
```

This works in tmux or in a Windows console window you type into. It does **not** work under
systemd or any start without a console: the node cannot ask and does not start. Either keep it
in tmux, or convert the key to plain once ([below](#convert-an-encrypted-key-to-plain)). The
wallet opens an encrypted key with `--node-key` or as the account `node`, and asks the node's
password; it needs about 1 GB of free memory for that.

### Docker, plain key

1. Stop the node, and save the keys the container may have made at its first start:

```sh
docker compose stop
sudo cp -a ~/.credits/keys ~/.credits/keys.generated-$(date +%F)
```

2. Copy your two files in, owned by the container's user (uid 1000), mode 600:

```sh
sudo cp NodePrivate.txt NodePublic.txt ~/.credits/keys/
sudo chown 1000:1000 ~/.credits/keys/NodePrivate.txt ~/.credits/keys/NodePublic.txt
sudo chmod 600 ~/.credits/keys/NodePrivate.txt ~/.credits/keys/NodePublic.txt
```

3. Start it and check the key it runs with:

```sh
docker compose up -d
docker compose exec node credits-wallet account node-key
```

`address` must be your `NodePublic.txt`, with `public file : ... matches`. The log must not
show `new node keys` nor ask for a password. (The node does not print its own key in the log.)

On a **new** installation you can put the two files in `~/.credits/keys/` (with the `chown` and
`chmod` above) before the first `docker compose up -d`: the container makes new keys only when
`keys/NodePublic.txt` is missing. Always copy both files.

### Docker, encrypted key

The container cannot type a password, so convert the key to plain once, with the node from the
same image, then continue as for a plain key.

1. Stop the node and save its current keys (step 1 above).
2. Put the encrypted files in a temporary folder owned by uid 1000:

```sh
mkdir ~/keyconv
cp /path/to/old/NodePrivate.txt /path/to/old/NodePublic.txt ~/keyconv/
sudo chown -R 1000:1000 ~/keyconv && sudo chmod 700 ~/keyconv
```

3. Decrypt it. Type `p`, Enter, then the password and Enter. The node then waits about 10 seconds
(two 5-second countdowns: press nothing) and exits with `Keys dumped to /keyconv/keys.json`.
It needs no network and touches no data.

```sh
docker run --rm -it --network none -v ~/keyconv:/keyconv -w /opt/credits \
--entrypoint /opt/credits/node ghcr.io/creditscommunity/credits-node:latest \
--config-file config.ini.template --db-path /tmp/db \
--public-key-file /keyconv/NodePublic.txt --private-key-file /keyconv/NodePrivate.txt \
--dumpkeys /keyconv/keys.json
```

A wrong password prints `Incorrect password (or corrupted file)` and asks again. If it asks
to rewrite the public key file, your `NodePublic.txt` does not belong to this key: type `q`
to stop, or `f` to write the right one.

4. Write the two plain files (no newline at the end, mode 600, owner 1000):

```sh
docker run --rm -v ~/keyconv:/keyconv --entrypoint python3 \
ghcr.io/creditscommunity/credits-node:latest -c "import json,os; \
k=json.load(open('/keyconv/keys.json'))['key']; os.umask(0o077); os.makedirs('/keyconv/plain', exist_ok=True); \
open('/keyconv/plain/NodePrivate.txt','w').write(k['private']); open('/keyconv/plain/NodePublic.txt','w').write(k['public'])"
```

5. Install them, then delete the decrypted copies:

```sh
sudo cp -p ~/keyconv/plain/NodePrivate.txt ~/keyconv/plain/NodePublic.txt ~/.credits/keys/
sudo shred -u ~/keyconv/keys.json ~/keyconv/plain/NodePrivate.txt ~/keyconv/plain/NodePublic.txt \
~/keyconv/NodePrivate.txt ~/keyconv/NodePublic.txt
sudo rm -r ~/keyconv
```

6. Start and check, as in step 3 for a plain key.

### Convert an encrypted key to plain

Native variant, for example to run the node under systemd: the same `--dumpkeys` with the
package's `node`, in the `csnode` folder with the node **stopped** and the encrypted
`NodePrivate.txt` and `NodePublic.txt` in place.

```sh
cp NodePrivate.txt ~/NodePrivate.encrypted.bak # move it offline afterwards
./node --config-file config.ini --db-path /tmp/keyconv-db --dumpkeys keys.json
python3 -c "import json,os; k=json.load(open('keys.json'))['key']; os.umask(0o077); \
open('NodePrivate.txt','w').write(k['private']); open('NodePublic.txt','w').write(k['public'])"
chmod 600 NodePrivate.txt
shred -u keys.json && rm -rf /tmp/keyconv-db
```

Type `p` and the password as above. Without `python3`:
`jq -j .key.private keys.json > NodePrivate.txt` and `jq -j .key.public keys.json > NodePublic.txt`.
The node then starts without asking anything. On Windows use `node.exe` the same way, then in
PowerShell:

```powershell
$k = (Get-Content keys.json | ConvertFrom-Json).key
[IO.File]::WriteAllText("$PWD\NodePrivate.txt", $k.private); [IO.File]::WriteAllText("$PWD\NodePublic.txt", $k.public)
Remove-Item keys.json
```

## 11. Troubleshooting

| Problem | What to do |
|---|---|
Expand Down
Loading