ECN node install

Install a PolitiCap ECN node and connect it as a downlink to the Nakhon Nayok hub. This page is the canonical install manual for the node package.

What you get

The politicap-node package is a self-contained regional market stack:

Component	Role
`bin/politicap-api`	Market API binary (same build as the hub)
`etc/politicap-api.yaml`	Node identity, uplink URL + API key, local database
`db/schema.sql` + `db/seed.sql`	Schema + catalog seed (countries, cities, tickers, hub row)
`systemd/politicap-api.service`	Service unit

Topology

Nakhon Nayok hub (root uplink)
        ▲
        │  header X-ECN-Node-Key: pcn_…
        │
   your regional node (downlink)
   {city}.{country}.politicap.eu

Frontend for humans stays politicap.eu (signup, content, account).
Your node serves the regional market API on your hostname.
The hub is the parent for all descendants until multi-hop trees are introduced.

Prerequisites

Linux host with systemd (Debian/Ubuntu recommended)
MySQL or MariaDB 10.5+
Outbound HTTPS to https://api.politicap.eu (hub)
A node API key issued by the hub operator (prefix pcn_) — private channel only
Public DNS for {city}.{country}.politicap.eu (and TLS when you go live)

Contact support@politicap.eu if you need a downlink provisioned.

1. Unpack

tar -xzf politicap-node-*.tar.gz
cd politicap-node-*
sudo mkdir -p /opt/politicap-api/bin /etc/politicap-api
sudo cp bin/politicap-api /opt/politicap-api/bin/
sudo chmod 755 /opt/politicap-api/bin/politicap-api

2. Database

sudo mysql -e "CREATE DATABASE politicap CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'politicap'@'localhost' IDENTIFIED BY 'STRONG_PASSWORD';
GRANT ALL ON politicap.* TO 'politicap'@'localhost';
FLUSH PRIVILEGES;"

mysql -u politicap -p politicap < db/schema.sql
mysql -u politicap -p politicap < db/seed.sql

Seed loads catalog data only (no foreign user books). You can refresh tickers later from the hub catalog API.

3. Configure

sudo cp etc/politicap-api.yaml.example /etc/politicap-api/politicap-api.yaml
sudo edit /etc/politicap-api/politicap-api.yaml

Minimum fields:

node:
  name: "Your node name"
  hostname: your-city.your-country.politicap.eu
  role: regional
  ecn_id: 1

listen:
  addr: "0.0.0.0:18082"

database:
  user: politicap
  password: "STRONG_PASSWORD"
  host: "127.0.0.1"
  port: "3306"
  name: politicap

uplink:
  url: "https://api.politicap.eu"
  api_key: "pcn_YOUR_KEY_FROM_HUB"

public:
  site_url: https://politicap.eu
  api_url: https://your-city.your-country.politicap.eu

Environment variables override the file (e.g. DB_PASSWORD, ECN_UPLINK_API_KEY, POLITICAP_CONFIG).

4. systemd

sudo cp systemd/politicap-api.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now politicap-api
sudo systemctl status politicap-api
curl -sS http://127.0.0.1:18082/healthz

5. Handshake with the hub

export KEY='pcn_…'   # from hub operator
curl -sS -H "X-ECN-Node-Key: $KEY" \
  https://api.politicap.eu/api/ecn/v1/hello | jq .

Expected: "ok": true, your node status becomes online on the hub, last_hello_at set.

6. Pull catalog

curl -sS -H "X-ECN-Node-Key: $KEY" \
  'https://api.politicap.eu/api/ecn/v1/catalog/tickers?limit=500' | jq '.count, .tickers[0]'

curl -sS -H "X-ECN-Node-Key: $KEY" \
  https://api.politicap.eu/api/ecn/v1/catalog/countries | jq '.countries|length'

Apply updates into your local DB as you automate (import job is operator-side for now).

7. Public edge (when ready)

DNS: {city}.{country}.politicap.eu → your load balancer / host
TLS: prefer *.{country}.politicap.eu (Let’s Encrypt does not issue *.*.politicap.eu)
Reverse proxy → 127.0.0.1:18082

API reference (downlink → hub)

Method	Path	Auth
GET/POST	`/api/ecn/v1/hello`	`X-ECN-Node-Key`
GET	`/api/ecn/v1/me`	node key
GET	`/api/ecn/v1/catalog/tickers`	node key
GET	`/api/ecn/v1/catalog/countries`	node key
GET	`/api/ecn/v1/catalog/cities?country_id=`	node key

Bearer form is also accepted: Authorization: Bearer pcn_….

Security

Treat pcn_ keys like production secrets. The hub stores only a hash.
Do not commit keys or DB passwords.
Restrict admin ports; expose only the API via TLS.
Support: support@politicap.eu

What this release does not include yet

Automatic apply of catalog pull into the local DB
Cross-ECN order batching (ecn_to_ecn)
Regional DutchBud ledgers (ledger remains hub-central for now)

Those land as the syndicate grows. Handshake + catalog + local market API are the foundation.

Package source

Hub operators build packages with scripts/build-node-package.sh in the politicap-api repository. Operators receive a versioned politicap-node-*.tar.gz plus a one-time API key.