Fystack Self-host Quick Start Guide

Welcome to Fystack! This guide will help you get up and running quickly with our infrastructure, including:

• Apex: The backend core API
• MPCIUM: Self-hosted MPC nodes for secure signing and key management

Platform Support

Platform	Status
Linux	Fully supported
macOS	Fully supported (requires Docker Desktop)
Windows	Supported via WSL2 (see below)

---

Overview

Fystack is a self-hosted custodial wallet platform built on MPC (Multi-Party Computation) so you can run secure threshold cryptography on hardware you control—no third-party custody required.

With Fystack you keep full ownership of:

• MPC nodes that handle distributed keygen and signing
• Key material and policies with no external dependencies
• Threshold signature security that scales across on-prem and private cloud setups

Run ./fystack-ignite.sh to spin up the entire test stack in minutes. The quick start gives you hands-on access to Apex plus a local MPCIUM cluster so you can explore the architecture, build against real services, and validate the workflow before production.

---

Components

1. Apex (Backend Core)

The API backend that handles:

• Wallet and User management
• Key orchestration and policy enforcement
• Audit logging
• API Keys
• Transaction indexing

2. MPCIUM (MPC Nodes)

Each node runs part of the threshold signing/keygen logic (based on Binance's tss-lib) and communicates securely with Apex and otherpeers.

3. Multichain Indexer

Indexes the latest blocks from the blockchain in real-time, keeping track of on-chain transactions and events relevant to your wallets.

4. Rescanner

Reindexes block gaps to ensure complete blockchain data coverage, filling in any missing blocks or transactions that may have been skipped during initial indexing.

---

Prerequisites

• Docker and Docker Compose installed
• Bash shell
• Internet connection
• Recommended system: 4 vCPU, 4 GB RAM

Windows (WSL2)

Non-Windows users can skip this section.

Windows users must run the scripts inside WSL2 (Windows Subsystem for Linux). Docker Desktop for Windows already uses WSL2 under the hood, so this is the natural fit.

1. Install WSL2 (if you haven't already)

Open PowerShell as Administrator and run:

wsl --install

This installs WSL2 with Ubuntu by default. Restart your machine when prompted.

2. Install Docker Desktop for Windows

Download and install Docker Desktop. During setup, ensure "Use the WSL 2 based engine" is checked (it's the default).

After installation, go to Docker Desktop Settings > Resources > WSL Integration and enable integration for your WSL2 distro (e.g., Ubuntu).

3. Install jq inside WSL2

Open your WSL2 terminal (Ubuntu) and run:

sudo apt update && sudo apt install -y jq

4. Open a WSL2 terminal

All subsequent commands must be run from within a WSL2 terminal, not from PowerShell or CMD. The docker command inside WSL2 talks to Docker Desktop automatically.

wsl

Quick Start Steps

📺 Video Tutorial: Watch the complete setup walkthrough on YouTube:

1. Clone the Repository

git clone git@github.com:fystack/fystack-selfhost-scripts.git
cd fystack-selfhost-scripts

2. Docker Login

First, authenticate with the Fystack Labs Docker registry:

docker login -u fystacklabs

When prompted, enter your password.

Need the Docker password? Join the Fystack Telegram community to get access:

3. Copy config files from the template

cp ./dev/config.yaml.template ./dev/config.yaml
cp ./dev/config.rescanner.yaml.template ./dev/config.rescanner.yaml
cp ./dev/config.indexer.yaml.template ./dev/config.indexer.yaml

Important: You don't need to update all configuration values. The only mandatory configuration is the CoinMarketCap API key. Visit https://pro.coinmarketcap.com/login/ to create a CoinMarketCap API key, then add it to config.yaml under the price_providers configuration.

4. Make Start Script Executable

Change to the root directory, make the start script executable. Make sure you are at the root folder of the project

chmod +x ./fystack-ignite.sh

5. Start the Fystack Cluster

Run the complete setup and startup script at the root folder of the project.

./fystack-ignite.sh

This script will automatically:

• Generate MPCIUM node configurations
• Start all Docker Compose services
• Extract encryption keys
• Configure and restart the Apex service

Services started include:

• NATS messaging server (port 4223)
• Consul service discovery (port 8501)
• PostgreSQL database (port 5433)
• Redis (port 6380)
• MongoDB (port 27018)
• Apex API (port 8150)
• 3 MPC nodes (node0, node1, node2)
• Automatic peer registration

6. Visit the Fystack Portal

Once all services are running, you can access the Fystack portal at http://localhost:8015

7. Verify the Setup

Check that all services are running:

docker compose -f ./dev/docker-compose.yaml ps

You should see all services in the "Up" state.

8. View Logs (Optional)

Monitor the cluster logs:

# View all service logs
docker compose -f ./dev/docker-compose.yaml logs -f

# View logs from a specific node
docker compose -f ./dev/docker-compose.yaml logs -f mpcium-node0

What's Running

Your Fystack cluster includes:

Note: PostgreSQL, Redis, MongoDB, NATS, and Consul ports have been increased by 1 to avoid conflicts with your development environment. All ports are bound to 127.0.0.1 (localhost) for security.

Service	Purpose	Port
NATS Server	Messaging layer for node communication	4223
Consul	Service discovery and health checks	8501
PostgreSQL	Database for custody operations	5433
Redis	In-memory data store	6380
MongoDB	Document database	27018
Apex API	Main API service	8150
Migrate	Database migration service	-
Rescanner	Reindexes block gaps for complete data	-
Multichain Indexer	Indexes blockchain transactions in real-time	-
Fystack UI Community	Community web interface for Fystack	8015
MPC Node 0	First MPC node	8080
MPC Node 1	Second MPC node	8081
MPC Node 2	Third MPC node	8082
MPCIUM Init	Peer registration service	-

E2E Testing

Once your Fystack cluster is running, you can test the wallet creation flow using the provided end-to-end test script.

1. Make Test Script Executable

Make the E2E test script executable:

chmod +x ./e2e/create-wallet.sh

2. Run the E2E Test

Execute the wallet creation test:

./e2e/create-wallet.sh

This script will:

• Register a test user
• Sign in and create a workspace
• Start a session
• Create an MPC wallet

3. Check Apex API Logs

Monitor the Apex API logs to verify successful wallet creation:

docker compose -f ./dev/docker-compose.yaml logs -f apex

Expected successful output:

3:15AM INF Enqueueing message
3:15AM INF Message published message len=407 topic=auditlog.event.dispatch
3:15AM INF Received message meta={"Consumer":"event","Domain":"","NumDelivered":1,"NumPending":0,"Sequence":{"consumer_seq":2,"stream_seq":2},"Stream":"auditlog","Timestamp":"2025-08-06T03:15:55.887251886Z"}
3:15AM INF Message Acknowledged meta={"Consumer":"event","Domain":"","NumDelivered":1,"NumPending":0,"Sequence":{"consumer_seq":2,"stream_seq":2},"Stream":"auditlog","Timestamp":"2025-08-06T03:15:55.887251886Z"}
3:15AM INF Received message meta={"Consumer":"mpc_keygen_result","Domain":"","NumDelivered":1,"NumPending":0,"Sequence":{"consumer_seq":1,"stream_seq":1},"Stream":"mpc","Timestamp":"2025-08-06T03:15:59.081703423Z"}
3:15AM INF Process MPC generation successfully walletID=a8f47f60-540d-4d23-8743-6fd8b5abe5ce
3:15AM INF Message Acknowledged meta={"Consumer":"mpc_keygen_result","Domain":"","NumDelivered":1,"NumPending":0,"Sequence":{"consumer_seq":1,"stream_seq":1},"Stream":"mpc","Timestamp":"2025-08-06T03:15:59.081703423Z"}

4. Check MPC Node Logs

Verify the MPC key generation process on any node (e.g., node0):

docker compose -f ./dev/docker-compose.yaml logs -f mpcium-node0

Expected successful output:

2025-08-06 03:15:55.000 INF Initializing session with partyID: {1,keygen}, peerIDs [{0,keygen} {1,keygen} {2,keygen}]
2025-08-06 03:15:55.000 INF [INITIALIZED] Initialized session successfully partyID: {1,keygen}, peerIDs [{0,keygen} {1,keygen} {2,keygen}], walletID a8f47f60-540d-4d23-8743-6fd8b5abe5ce, threshold = 2
2025-08-06 03:15:55.000 INF Initializing session with partyID: {1,keygen}, peerIDs [{0,keygen} {1,keygen} {2,keygen}]
2025-08-06 03:15:55.000 INF [INITIALIZED] Initialized session successfully partyID: {1,keygen}, peerIDs [{0,keygen} {1,keygen} {2,keygen}], walletID a8f47f60-540d-4d23-8743-6fd8b5abe5ce, threshold = 2
2025-08-06 03:15:56.000 INF Starting to generate key ECDSA walletID=a8f47f60-540d-4d23-8743-6fd8b5abe5ce
2025-08-06 03:15:56.000 INF Starting to generate key EDDSA walletID=a8f47f60-540d-4d23-8743-6fd8b5abe5ce
2025-08-06 03:15:59.000 INF Publishing message consumerName=mpc_keygen_result topic=mpc.mpc_keygen_result.a8f47f60-540d-4d23-8743-6fd8b5abe5ce
2025-08-06 03:15:59.000 INF [COMPLETED KEY GEN] Key generation completed successfully walletID=a8f47f60-540d-4d23-8743-6fd8b5abe5ce

The successful completion of these logs indicates that your MPC wallet has been created and the key generation process completed across all nodes.

Deploying on a VPS / Reverse Proxy

By default, the Fystack UI connects to the Apex API at http://localhost:8150. If you're deploying on a VPS (e.g., Linode, DigitalOcean) behind a reverse proxy, you need to set the API_BASE_URL environment variable so the UI can reach the API.

Option 1: Export the variable before running the script

export API_BASE_URL=https://api.yourdomain.com
./fystack-ignite.sh

Option 2: Create a .env file in the dev/ directory

echo "API_BASE_URL=https://api.yourdomain.com" > dev/.env
./fystack-ignite.sh

Replace https://api.yourdomain.com with the public URL where your Apex API is accessible through your reverse proxy.

Changing the API URL later

To update the API_BASE_URL after the initial setup (e.g., switching domains):

export API_BASE_URL=https://new-domain.com
docker compose -f ./dev/docker-compose.yaml up -d --force-recreate fystack-ui-community

This recreates the UI container with the new URL. No other services are affected.

Update version

To update version of a component (New docker image version)

cd dev
docker compose pull apex
docker compose up -d --no-deps --force-recreate apex

---

⚠️ Important Notice

WARNING: This setup is for testing environments only.

For manual deployment, Docker Compose, or Kubernetes deployment for maximum security, please contact the Fystack team to get support and guidance on enterprise-grade deployment configurations.