https://github.com/fystack/fystack-selfhost-scripts
Self host crypto custody platform with one single command line
https://github.com/fystack/fystack-selfhost-scripts
crypto custody multichain
Last synced: 4 months ago
JSON representation
Self host crypto custody platform with one single command line
- Host: GitHub
- URL: https://github.com/fystack/fystack-selfhost-scripts
- Owner: fystack
- Created: 2025-08-05T04:12:10.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-02-09T05:42:43.000Z (5 months ago)
- Last Synced: 2026-02-09T11:34:45.898Z (5 months ago)
- Topics: crypto, custody, multichain
- Language: Shell
- Homepage: https://fystack.io/blog/open-source-fystack-ignite-self-host-a-full-fledged-stablecoin-custody-platform-with-one-command-line
- Size: 11.9 MB
- Stars: 15
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# 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:
```powershell
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](https://www.docker.com/products/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:
```bash
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.
```bash
wsl
```
## Quick Start Steps
> **📺 Video Tutorial:** Watch the complete setup walkthrough on YouTube:
>
> [](https://www.youtube.com/watch?v=AjY9t7orbs4)
### 1. Clone the Repository
```bash
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:
```bash
docker login -u fystacklabs
```
When prompted, enter your password.
> **Need the Docker password?** Join the Fystack Telegram community to get access:
>
> [](https://t.me/+9AtC0z8sS79iZjFl)
### 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
```bash
chmod +x ./fystack-ignite.sh
```
### 5. Start the Fystack Cluster
Run the complete setup and startup script at the root folder of the project.
```bash
./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](http://localhost:8015)
### 7. Verify the Setup
Check that all services are running:
```bash
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:
```bash
# 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:
```bash
chmod +x ./e2e/create-wallet.sh
```
### 2. Run the E2E Test
Execute the wallet creation test:
```bash
./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:
```bash
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):
```bash
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**
```bash
export API_BASE_URL=https://api.yourdomain.com
./fystack-ignite.sh
```
**Option 2: Create a `.env` file in the `dev/` directory**
```bash
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):
```bash
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.
>
> [](https://t.me/+IsRhPyWuOFxmNmM9)