Skip to content

Commit 55b78bd

Browse files
werner-stacksgitbook-bot
werner-stacks
authored and
gitbook-bot
committed
GITBOOK: Run a Signer: compress to an overview and routing page
1 parent cc95631 commit 55b78bd

2 files changed

Lines changed: 65 additions & 287 deletions

File tree

‎docs/operate/run-a-signer/README.md‎

Lines changed: 62 additions & 284 deletions
Original file line numberDiff line numberDiff line change
@@ -1,330 +1,108 @@
1-
# Run a Signer
2-
3-
<div data-with-frame="true"><figure><img src="../.gitbook/assets/run-a-signer-cover.png" alt=""><figcaption></figcaption></figure></div>
4-
5-
### How to Use This Guide
6-
7-
This guide is a step-by-step walkthrough for setting up and running a signer. It covers only the signer infrastructure: the signer software and the Stacks node it connects to.
8-
9-
If you are not familiar with the concept of signing, be sure to check out the [Stackers and Signing concept guide](https://github.com/stacks-network/docs/blob/master/docs/learn/block-production/signing.md).
10-
11-
### Background and High-Level Process
12-
13-
To run a signer you'll run a signer and a Stacks node side-by-side. Specifically, run a follower node. The signer monitors events from the Stacks node and uses the generated account (see Preflight Setup) to sign incoming Stacks blocks sent from the Stacks node.
14-
15-
This doc provides instructions to set up both using either Docker or the release binaries available in the [stacks core releases](https://github.com/stacks-network/stacks-core/releases/latest) repository, and how to configure them so the signer and Stacks node communicate correctly.
16-
17-
### Knowledge Prerequisites
18-
19-
* Docker and basic knowledge of pulling and running images
20-
* Basic knowledge of [Stacks accounts](https://github.com/stacks-network/docs/blob/master/docs/learn/network-fundamentals/wallets-and-accounts.md)
21-
22-
{% stepper %}
23-
{% step %}
24-
#### Signer Checklist: Pre-Launch Setup
25-
26-
Quick reference of major setup steps prior to launching a signer.
27-
28-
* Ensure your system meets the [minimum system requirements](./#minimum-system-requirements).
29-
* Acquire Docker and basic knowledge of Stacks accounts (links above).
30-
{% endstep %}
31-
32-
{% step %}
33-
#### Signer Checklist: Preflight Setup
34-
35-
* Generate a new private key using stacks-cli (see Preflight Setup).
36-
* Save the generated account information securely.
37-
{% endstep %}
38-
39-
{% step %}
40-
#### Signer Checklist: Configuration Setup
41-
42-
* Create a `signer-config.toml` file with necessary configurations:
43-
* node\_host
44-
* endpoint
45-
* network
46-
* db\_path
47-
* auth\_password
48-
* stacks\_private\_key
49-
* Store `signer-config.toml` securely and note down the values used.
50-
{% endstep %}
51-
52-
{% step %}
53-
#### Signer Checklist: Running the Signer
54-
55-
* Decide whether to run the signer using Docker (recommended) or as a binary.
56-
* If using Docker:
57-
* Set up the necessary ports and volumes.
58-
* Run the Docker container with the appropriate settings.
59-
* If running as a binary:
60-
* Build `stacks-core` from source or download the pre-built binary.
61-
* Run the signer using: `stacks-signer run --config <path_to_config>`.
62-
{% endstep %}
1+
---
2+
description: >-
3+
What a Stacks signer is made of, what it needs from the machine and the
4+
network, and where each piece is set up.
5+
---
636

64-
{% step %}
65-
#### Signer Checklist: Verify Signer Operation
66-
67-
* Check that the signer is listening on its configured endpoint.
68-
* Confirm that there are no errors and that the system is ready for connections.
69-
{% endstep %}
70-
71-
{% step %}
72-
#### Signer Checklist: Setting Up the Stacks Node
73-
74-
* Create a `node-config.toml`, include:
75-
* connection\_options.sauth\_token
76-
* events\_observer.endpoint (matching signer config)
77-
* Decide whether to run the Stacks node using Docker or as a binary and follow the respective run steps.
78-
{% endstep %}
79-
80-
{% step %}
81-
#### Signer Checklist: Verify Stacks Node Operation
82-
83-
* Check Stacks node logs for successful connection to the signer.
84-
* Confirm the node is syncing Bitcoin headers properly.
85-
{% endstep %}
86-
{% endstepper %}
87-
88-
### Minimum System Requirements
89-
90-
These are the minimum required specs to run a node and signer. More resources are recommended for optimal performance.
91-
92-
#### Signer, Stacks node and Bitcoin node
93-
94-
* 4 vCPU
95-
* 8 GB memory if running only a Stacks node and signer
96-
* 16 GB memory if running Stacks + Bitcoin node + signer
97-
* 1.5+ TB storage (1 TB for Bitcoin node, 500 GB for Stacks node, and 50 GB for signer)
98-
99-
***
100-
101-
## Preflight Setup
102-
103-
Before you get your signer set up, you'll need to [generate a new private key](https://docs.stacks.co/stacks-101/accounts#creation). The `stacks-cli` provides a mechanism for quickly generating a new account keychain via a simple CLI interface. The linked guide shows how to create one of those accounts on testnet.
104-
105-
Save the generated account information securely; you'll need it later.
106-
107-
{% hint style="info" %}
108-
What should the networking setup look like?
109-
110-
Signers are intended to work with a local node. The node<->signer connection is not run over SSL, which means you can be exposed to a man-in-the-middle attack if your signer and node are hosted on separate machines. Ensure your signer isn't allowing requests from the public internet. We recommend having the signer and node running locally on the same machine or using internal networking between them.
111-
{% endhint %}
7+
# Run a Signer
1128

113-
***
9+
<div data-with-frame="true"><figure><img src="https://4065274862-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4cpTb2lbw0LAOuMHrvhA%2Fuploads%2Fn6Drb2IOHQHE6IPyghA7%2Frun-a-signer-cover.png?alt=media&#x26;token=8791bf7e-2040-4e81-8cff-9337cdcd4a1b" alt="Run a Signer"><figcaption></figcaption></figure></div>
11410

115-
## Create a Configuration File
11+
A signer validates proposed Stacks blocks and signs the ones it accepts. This section covers the infrastructure: what has to be running, what it needs from the machine and the network, and where each piece is set up.
11612

117-
Create a file named `signer-config.toml`. Populate it with the example signer config file contents from the [Sample Configuration Files](https://github.com/stacks-network/docs/blob/master/docs/reference/node-operations/signer-configuration.md) page. Each field is described on that page.
13+
If signing is new to you, start with the [Signing concept guide](https://docs.stacks.co/learn/block-production/signing).
11814

11915
***
12016

121-
## Running the Signer
122-
123-
Two options: Docker (recommended) or binary. Binaries are available on the [Stacks Core releases page](https://github.com/stacks-network/stacks-core/releases/latest).
124-
125-
### Running the Signer with Docker
126-
127-
You can run the signer as a Docker container using the `blockstack/stacks-signer:3.1.0.0.5.0` image.
128-
129-
Requirements when running the container:
130-
131-
* The port configured as the `endpoint` (example: 30000) must be exposed to your Stacks node (endpoint should not be public).
132-
* A volume with at least a few GB available that contains the folder specified by your `db_path` (example: `/var`).
133-
* Mount your `signer-config.toml` file as a volume.
134-
135-
Example docker run command:
136-
137-
```bash
138-
IMG="blockstack/stacks-signer"
139-
VER="3.1.0.0.5.0"
140-
STX_SIGNER_PATH="./"
141-
STX_SIGNER_DATA="$STX_SIGNER_PATH/data"
142-
STX_SIGNER_CONFIG="$STX_SIGNER_PATH/signer-config.toml"
143-
144-
docker run -d \
145-
-v $STX_SIGNER_CONFIG:/config.toml \
146-
-v $STX_SIGNER_DATA:/var/stacks \
147-
-p 30000:30000 \
148-
-e RUST_BACKTRACE=full \
149-
-e BLOCKSTACK_DEBUG=0 \
150-
--name stacks-signer \
151-
$IMG:$VER \
152-
stacks-signer run \
153-
--config /config.toml
154-
```
155-
156-
{% hint style="info" %}
157-
If you get an error about the manifest not found or the image platform not matching the host platform, you probably are running on an architecture other than x64. Add `--platform=linux/amd64` to the command (for example, on M1 Mac).
158-
{% endhint %}
159-
160-
Or, using a custom Dockerfile:
161-
162-
```docker
163-
FROM blockstack/stacks-signer:3.1.0.0.5.0
164-
COPY signer-config.toml /config.toml
165-
EXPOSE 30000
166-
CMD ["stacks-signer", "run", "--config", "/config.toml"]
167-
```
168-
169-
### Running the Signer as a Binary
17+
## What has to be running
17018

171-
Download the pre-built binaries from the [Stacks Core releases page on Github](https://github.com/stacks-network/stacks-core/releases/latest), unzip the archive for your architecture. It includes the `stacks-signer` binary.
19+
These run alongside each other, and each depends on the one below it.
17220

173-
Run the signer:
21+
<table><thead><tr><th width="170">Process</th><th>What it does</th><th>Where to set it up</th></tr></thead><tbody><tr><td><code>stacks-signer</code></td><td>Validates proposed blocks and signs them with your signer key</td><td><a href="signer-quickstart.md">Signer Quickstart</a>, step 2</td></tr><tr><td><code>stacks-node</code></td><td>Follows the chain and streams block proposals to the signer. A follower, not a miner</td><td><a href="signer-quickstart.md">Signer Quickstart</a>, step 4</td></tr><tr><td><code>bitcoind</code></td><td>Feeds the Stacks node its view of Bitcoin. Run your own, dedicated to this signer</td><td><a href="../run-a-node/run-a-bitcoin-node.md">Run a Bitcoin Node</a> or <a href="../run-a-node/run-a-pruned-bitcoin-node.md">Run a Pruned Bitcoin Node</a></td></tr></tbody></table>
17422

175-
```bash
176-
stacks-signer run --config ../signer-config.toml
177-
```
23+
A shared or third-party Bitcoin node is the usual reason a Stacks node falls behind tip and stays there, and a signer whose node is behind tip stops signing. Treat a dedicated Bitcoin node as part of the signer, not as an optional extra.
17824

179-
(Replace `../signer-config.toml` with the actual path to your config.)
25+
The Quickstart runs both the signer and the node end to end, with binary and Docker paths. Field-by-field descriptions of both config files live in [Signer Configuration](https://docs.stacks.co/reference/node-operations/signer-configuration) and [Stacks Node Configuration](https://docs.stacks.co/reference/node-operations/readme-1).
18026

18127
***
18228

183-
## Verify the Signer is Running
29+
## Minimum system requirements
18430

185-
List running containers:
31+
These are minimums for the signer, the Stacks node and a Bitcoin node together. Provision above them if you can.
18632

187-
```bash
188-
docker ps
189-
```
190-
191-
Check the container logs:
192-
193-
```bash
194-
docker logs <container-id>
195-
```
196-
197-
You should see:
198-
199-
Signer spawned successfully. Waiting for messages to process...
200-
201-
You may also see a warning like:
202-
203-
```
204-
WARN [1712003997.160121] [stacks-signer/src/runloop.rs:247] [signer_runloop] Signer is not registered for reward cycle 556. Waiting for confirmed registration...
205-
```
206-
207-
This means your signer is running and awaiting registration; proceed to set up the Stacks node and then begin stacking.
208-
209-
{% hint style="warning" %}
210-
You may see messages saying the signer is not registered for the current or next reward cycle. This is normal until the prepare phase for your chosen reward cycle; assuming you meet the stacking minimum, the signer will be registered during that phase.
211-
{% endhint %}
33+
* 4 vCPU
34+
* 8 GB memory for the signer and Stacks node, 16 GB with a Bitcoin node alongside them
35+
* 1.5 TB storage or more: roughly 1 TB for the Bitcoin node, 500 GB for the Stacks node, 50 GB for the signer
21236

21337
***
21438

215-
## Set Up Your Bitcoin Node
39+
## Networking
21640

217-
Optional but recommended to improve signer health and performance.
41+
The signer and the node talk over plain HTTP. The signer builds its node URL as `http://{node_host}`, and the `auth_password` it sends is your node's `auth_token`, in the clear. Anything that can observe that link can read the token and impersonate your node to the signer.
21842

219-
Guides:
43+
Keep both on the same private network, with the signer reachable only from the node. Loopback on a single machine is the simplest way to do that. Separate hosts on a trusted private subnet is the better one, because a host running `stacks-node` participates in the peer-to-peer network and is easier to enumerate, so keeping the signer off it hides the signer. Either way, the signer's `endpoint` must never be reachable from the public internet.
22044

221-
* Run a full Bitcoin node: https://docs.stacks.co/guides-and-tutorials/nodes-and-miners/run-a-bitcoin-node
222-
* Run a pruned Bitcoin node: https://docs.stacks.co/guides-and-tutorials/nodes-and-miners/run-a-pruned-bitcoin-node
45+
User separation, systemd hardening and firewalling are covered in [OpSec Best Practices](opsec-best-practices.md).
22346

22447
***
22548

226-
## Set Up Your Stacks Node
227-
228-
Start the Stacks node after the signer is running. The node will not run unless it can send events to the signer.
229-
230-
### Stacks Node Configuration
231-
232-
Create `node-config.toml`. See the [Sample Configuration Files](https://github.com/stacks-network/docs/blob/master/docs/reference/node-operations/signer-configuration.md) page for the full contents.
233-
234-
Important fields to change:
49+
## Setup checklist
23550

236-
* `working_dir`: directory where the node persists data
237-
* `auth_token`: authentication token used by signer (must match signer `auth_password`)
238-
* `events_observer.endpoint`: host and port where your signer listens (example: `127.0.0.1:30000` or `stacks-signer.local:30000`)
239-
240-
### Start with an archive
241-
242-
Starting from an archive snapshot is much faster than syncing from genesis. Archives are at https://archive.hiro.so.
243-
244-
Example to download and extract the latest mainnet snapshot:
245-
246-
```bash
247-
curl -# https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz -o stacks-snapshot.tar.gz
248-
tar -zxvf stacks-snapshot.tar.gz
249-
```
250-
251-
This creates a `mainnet` folder where downloaded. Set `working_dir` to the parent directory containing `mainnet`.
252-
253-
See best practices for snapshots: ../best-practices-to-snapshot-the-chainstate.md
254-
255-
### Run a Stacks Node with Docker
256-
257-
Use the `blockstack/stacks-core` image (example tag: `3.1.0.0.13`).
258-
259-
When running the container:
51+
{% stepper %}
52+
{% step %}
53+
#### Provision the machine
26054

261-
* Expose the port configured for `p2p_bind` to the internet.
262-
* Make the port configured for `rpc_bind` accessible by your signer.
263-
* `working_dir` needs 500 GB–1 TB storage.
264-
* Include your `node-config.toml`.
55+
Meet the requirements above, and decide now whether the signer and node share a host or sit on a private subnet.
56+
{% endstep %}
26557

266-
Example docker run:
58+
{% step %}
59+
#### Generate the signer key
26760

268-
```bash
269-
IMG="blockstack/stacks-core"
270-
VER="3.1.0.0.13"
271-
STX_NODE_CONFIG="./node-config.toml"
61+
A fresh Stacks account, whose private key becomes `stacks_private_key`. Store it somewhere you can restore from. See [Signer Quickstart](signer-quickstart.md), step 1.
62+
{% endstep %}
27263

273-
docker run -d \
274-
-v $STX_NODE_CONFIG:/config.toml \
275-
-v /var/stacks \
276-
-p 20443:20443 \
277-
-p 20444:20444 \
278-
-e RUST_BACKTRACE=full \
279-
--name stacks-node \
280-
$IMG:$VER \
281-
stacks-node start \
282-
--config /config.toml
283-
```
64+
{% step %}
65+
#### Configure and start the signer
28466

285-
Or with a custom Dockerfile:
67+
`signer-config.toml` needs `node_host`, `endpoint`, `network`, `db_path`, `auth_password` and `stacks_private_key`. Verify it with `stacks-signer check-config` before starting.
68+
{% endstep %}
28669

287-
```docker
288-
FROM blockstack/stacks-core:3.1.0.0.13
289-
COPY node-config.toml /config.toml
290-
EXPOSE 20444
291-
EXPOSE 20443
292-
CMD ["stacks-node", "start", "--config", "/config.toml"]
293-
```
70+
{% step %}
71+
#### Configure and start the Stacks node
29472

295-
If you get connection refused errors, you may need to point `events_observer.endpoint` to the Docker signer container. If using default Docker bridge mode, `localhost` inside the container is not the host. Point the endpoint to the Docker host or the signer container hostname accordingly.
73+
`node-config.toml` needs `stacker = true`, an `auth_token` matching the signer's `auth_password`, and an `[[events_observer]]` pointing at the signer's `endpoint`. Start the signer first: the node will not run unless it can reach that endpoint.
74+
{% endstep %}
29675

297-
### Run a Stacks Node with a Binary
76+
{% step %}
77+
#### Confirm both are healthy
29878

299-
Download the pre-built `stacks-node` binary from the [Stacks Core releases](https://github.com/stacks-network/stacks-core/releases/latest).
79+
The signer logs `Signer spawned successfully`. The node logs `Registering event observer at` with your signer's endpoint, then begins syncing Bitcoin headers. Until your signer is in a reward set it will also log that it is not registered for the current cycle, which is expected.
80+
{% endstep %}
30081

301-
Start the node:
82+
{% step %}
83+
#### Register the signer
30284

303-
```bash
304-
./stacks-node start --config node-config.toml
305-
```
85+
Bind your signer key to a signer-manager contract. Until that happens the signer is running but has no stake behind it and signs nothing.
86+
{% endstep %}
87+
{% endstepper %}
30688

307-
### Verify Stacks Node is Running
89+
***
30890

309-
Typical startup logs:
91+
## Registering, once it runs
31092

311-
```bash
312-
Mar 6 19:35:08.212848 INFO stacks-node 0.1.0
313-
Mar 6 19:35:08.213084 INFO Loading config at path ./Stacks-config.toml
314-
Mar 6 19:35:08.216674 INFO Registering event observer at: localhost:30000
315-
Mar 6 19:35:08.221603 INFO Migrating sortition DB to the latest schema version
316-
Mar 6 19:35:08.224082 INFO Migrating chainstate DB to the latest schema version
317-
Mar 6 19:35:08.227404 INFO Start syncing Bitcoin headers, feel free to grab a cup of coffee, this can take a while
318-
```
93+
A running signer is not yet part of the signer set. Your signer key has to be bound to a signer-manager contract, and stakers have to route at least 50,000 STX through that manager in aggregate before it enters a cycle's signer set.
31994

320-
Ensure you see the `Registering event observer at XXX` log with your signer endpoint. Once Bitcoin headers are synced, you can GET `/v2/info` on the node RPC endpoint (default port 20443).
95+
Under PoX-5 that binding is a standing on-chain grant rather than PoX-4's per-transaction signature: you sign a SIP-018 message with your signer key, the signer-manager submits it through `grant-signer-key`, and then calls `register-signer`.
32196

322-
You may see many logs while syncing; refer to How to Read the Signer Logs if concerned.
97+
* [Generate a Signer Signature](../staking-stx/generate-signer-signature.md) produces the grant
98+
* [Staking STX](../staking-stx/) covers the staking side
99+
* [Key and Address Rotation](../staking-stx/key-and-address-rotation.md) covers changing the key later
323100

324101
***
325102

326-
## Next Steps: Stacking
327-
328-
Once your signer and Stacks node are running and verified, the next step is to stack STX to register your signer for a reward cycle. See the [Stacking STX](../staking-stx/) guide for complete instructions on solo stacking, delegated stacking, and managing your keys.
103+
## Running it well
329104

330-
You will need to [generate a signer signature](../staking-stx/generate-signer-signature.md) before making any stacking transaction.
105+
* [How to Read Signer Logs](how-to-read-signer-logs.md)
106+
* [How to Monitor Signer](how-to-monitor-signer.md)
107+
* [Best Practices to Run a Signer](best-practices-to-run-a-signer.md), including redundancy, fall-back deployments and auto-restart
108+
* [OpSec Best Practices](opsec-best-practices.md)

0 commit comments

Comments
 (0)