Installing Ecosystem

Install ScyllaDB, generate the wallet encryption key, enable the extension and verify the matching engine actually started — in the order that avoids losing data.

6 min readUpdated 3 August 2026install, scylladb, redis, kms, extension

Ecosystem installs in four stages: a ScyllaDB node, the vault key that encrypts every private key the addon will ever create, the extension itself, and a restart. The order matters. Creating a master wallet before the vault key exists fails; generating a new vault key after wallets exist destroys them.

The main installer does not touch any of this. There is not a single mention of ScyllaDB in installer.sh, and none of the variables below appear in .env.example. Every step here is manual.

Before you begin

A working Bicrypto install — backend, frontend and cron running under PM2
Redis reachable and answering PING (the core already requires it)
Root or sudo on the box that will run ScyllaDB
A valid Ecosystem license (Envato item 40071914) activated on this install
Shell access to the project root — several steps have no admin-panel equivalent
A safe place to store a passphrase you can never lose

ScyllaDB can live on the app box or its own. On the app box, budget for it properly: ScyllaDB wants 4 GB minimum and recommends roughly 2 GB per logical core. It is an SSD workload and it will fight the Node processes for memory on a small VPS.

1. Install ScyllaDB

ScyllaDB ships two official install paths. The web installer is what ScyllaDB recommends for new installs; the APT route gives you direct control over the repository, which matters if your server may not pipe a script from the internet into sudo bash.

curl -sSf get.scylladb.com/server | sudo bash

# or pin a release
curl -sSf get.scylladb.com/server | sudo bash -s -- --scylla-version 2026.1

sudo apt-get update
sudo apt-get install -y curl gpg wget

sudo mkdir -p /etc/apt/keyrings
sudo gpg --homedir /tmp --no-default-keyring --keyring /tmp/temp.gpg \
  --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys c503c686b007f39e
sudo gpg --homedir /tmp --no-default-keyring --keyring /tmp/temp.gpg \
  --export --armor c503c686b007f39e | sudo gpg --dearmor \
  -o /etc/apt/keyrings/scylladb.gpg
sudo wget -O /etc/apt/sources.list.d/scylla.list \
  https://downloads.scylladb.com/deb/debian/scylla-2026.1.list

sudo apt-get update
sudo apt-get install -y scylla

Modern ScyllaDB releases are self-contained and no longer need a separate Java 8 install. The signing key also moved: the fingerprint is now c503c686b007f39e, and the repository list lives under /deb/debian/ rather than /deb/ubuntu/.

Then configure and start it.

Edit /etc/scylla/scylla.yaml — two changes.

Change api_port: 10000 to api_port: 10001. Port 10000 is Virtualmin's default and the clash is silent until Scylla refuses to start.

Uncomment and set the authenticator so the cluster is not open to anything that can reach port 9042:
```
authenticator: PasswordAuthenticator
```
Run the setup wizard — it tunes the kernel, disks and network for you.
```
sudo scylla_setup
```

Start and enable the service.

sudo systemctl start scylla-server
sudo systemctl enable scylla-server
sudo systemctl status scylla-server

Create a role for the platform. The default superuser is cassandra:cassandra and must not stay that way.
```
cqlsh -u cassandra -p cassandra
```
Then, at the cqlsh prompt:
```
CREATE ROLE IF NOT EXISTS bicrypto
  WITH PASSWORD = 'a-long-random-password'
  AND LOGIN = true
  AND SUPERUSER = true;
```
Exit, reconnect with the new credentials, and run describe keyspaces; to prove they work.

Do not create keyspaces or tables by hand. The client creates SCYLLA_KEYSPACE and SCYLLA_FUTURES_KEYSPACE — and every table and index inside them — on its first successful connection, and it runs its own column migrations on every subsequent boot.

Port 9042 must be reachable from the backend and from nowhere else. Loopback or a private network only.

2. Add the ScyllaDB variables

None of these are in .env.example. Add them by hand to the project root .env.

SCYLLA_CONNECT_POINTS="127.0.0.1:9042"
SCYLLA_DATACENTER="datacenter1"
SCYLLA_USERNAME="bicrypto"
SCYLLA_PASSWORD="a-long-random-password"
SCYLLA_KEYSPACE="trading"
SCYLLA_FUTURES_KEYSPACE="futures"

SCYLLA_DATACENTER must match the datacenter name the node itself reports, not a name you choose. Authentication is only attached when both username and password are set — half a pair is the same as none.

If Scylla is unreachable the backend probes the first contact point with a short TCP check, logs that trading is unavailable, and carries on booting. Everything except trading keeps working. Setting SCYLLA_ENABLED="false" makes that state deliberate and stops the connection attempts entirely.

3. Generate the vault key

This is the step people skip and regret. The vault key encrypts every master wallet, every per-user deposit key and every custodial secret the addon will create.

node ./scripts/kms/generate.mjs

It generates a random 32-byte key, prompts for a passphrase of at least 12 characters, encrypts the key with AES-256-GCM (PBKDF2, 100,000 iterations, SHA-512) and writes the result back to .env as ENCRYPTED_ENCRYPTION_KEY — four colon-separated hex parts: IV, auth tag, ciphertext, salt.

If ENCRYPTED_ENCRYPTION_KEY is already set, the script prints "already set" and does nothing. That guard is deliberate.

The encrypted master key. Four colon-separated hex parts. Required for every wallet operation.

The passphrase that decrypts it. Optional — set it and the vault unlocks itself at boot; leave it out and an admin must unlock manually after every restart.

Lose the passphrase, or replace ENCRYPTED_ENCRYPTION_KEY with a fresh one, and every wallet already stored becomes permanently unreadable — including the addresses customers have already deposited to. No support process can undo it. Back up .env somewhere your database backup does not live, and store the passphrase separately from both.

The trade-off on ENCRYPTION_KEY_PASSPHRASE is real and yours to make. With it, restarts are unattended and withdrawals resume by themselves. Without it, the passphrase never touches the disk, but the vault starts locked after every restart and withdrawal signing stays dead until someone opens /admin/ecosystem and enters it.

4. Enable the extension

Activate the license. Go to Admin → System → Extensions, open Ecosystem, and verify the license. On a fresh purchase this is where the .lic file is written.
Check for updates, then update. Refresh the page when it finishes.
Enable the extension. The toggle only appears once the license is valid.
Apply it. From the project root:
```
pnpm updator
```
This stops the platform, installs dependencies, runs migrations and seeders, rebuilds the frontend and starts everything again. On a managed box a plain restart is not enough — the seeders are what create the ecosystem_blockchain rows the licensed chain addons need.

5. Verify

Four checks, in increasing order of confidence.

cqlsh -u bicrypto -p '…' -e "DESCRIBE KEYSPACE trading;"

You should see orders, candles, orderbook, trades, open_orders_by_market, eco_index_state and stop_orders. If the keyspace does not exist, the backend has never connected — check the logs for SCYLLA.

pm2 logs backend --lines 200 | grep -i "ECOSYSTEM\|SCYLLA"

Then open /admin/ecosystem. The masthead shows the vault state: a green "Vault Active" badge, or an "Initiate Vault" button if it is locked. Unlock it now if you did not set the passphrase.

Finally, open Ecosystem → Blockchains → Requirements. Nothing is configured yet, so every chain will report missing variables — that is the correct answer at this point, and that page is where you go next.

What is still missing

A working install at this point has an engine and no chains, no wallets, no tokens and no markets. In order:

The platform's own database backup covers MySQL and nothing else. Orders, candles, the trade tape and the order book have no backup path in the product. Set up nodetool snapshot or an equivalent before you take real orders, not after.