FreeSchema CLI

A command-line tool for deploying and managing a self-hosted FreeSchema stack with Docker.

Requirements

| Requirement | Version | |---|---| | Node.js | ≥ 16.0.0 | | Docker + Docker Compose | any recent version |

Installation

npm install -g freeschema

Quick Start

mkdir my-freeschema && cd my-freeschema
freeschema init                           # interactive setup wizard
freeschema start --local-db --local-mqtt  # start everything

Open your browser at http://localhost/wico (or http://localhost:<NGINX_PORT>/wico if you changed the port).

Commands

freeschema init

Interactive setup wizard. Run this once in an empty directory before anything else.

What it does:

1. Copies template files (docker-compose.yml, nginx/, mosquitto/, .env.example, etc.) into the current directory — existing files are never overwritten
2. Auto-generates a secure JWT_SECRET
3. Prompts you to configure:
   • Database — local MySQL container or external server
   • MQTT broker — local Mosquitto container or external broker
   • Nginx port — the port you will open in your browser (default 80)
   • SMTP — optional email sending credentials
   • Seed data — download the default dataset, load a local .sql file, or start empty
4. Creates .env and .env.frontend from the bundled examples

freeschema init

After init, edit .env to change any setting before starting.

freeschema start

Pulls the latest Docker images and starts all services. Requires .env and .env.frontend to exist (run init first).

freeschema start                              # external DB + external MQTT
freeschema start --local-db                   # spin up bundled MySQL
freeschema start --local-mqtt                 # spin up bundled Mosquitto
freeschema start --local-db --local-mqtt      # both local
freeschema start --local-db --seed ./data.sql # seed MySQL on every start

Flags:

| Flag | Alias | Description | |---|---|---| | --local-db | --db | Start the bundled MySQL container (Docker profile local-db) | | --local-mqtt | --mqtt | Start the bundled Mosquitto container (Docker profile local-mqtt) | | --seed <file> | | Load a .sql file into MySQL after it is ready (applied on every start) |

First-start behaviour with --local-db:

• Waits for MySQL to become healthy
• Auto-seeds from seed-db/coredb.sql if the database is empty and no --seed flag was given
• Applies --seed <file> if provided (bypasses auto-detect, applied on every start)
• Ensures sessions_db is in sync with freeschema_db
• Auto-runs setup-credentials to generate CLIENT_SECRET and save it to .env

freeschema stop

Stops all running services (equivalent to docker compose down).

freeschema stop

freeschema restart [service]

Restarts all services, or one specific service by name.

freeschema restart                  # restart everything
freeschema restart wico-server      # restart one container
freeschema restart nginx-server

freeschema status

Shows the current state of all containers (equivalent to docker compose ps).

freeschema status

freeschema logs [service]

Streams live logs. Without a service name, streams all containers.

freeschema logs                             # all services, live stream
freeschema logs wico-server                 # one service
freeschema logs wico-server --no-follow     # print and exit

Flags:

| Flag | Description | |---|---| | --no-follow | Print existing log output and exit instead of streaming |

freeschema pull

Pulls the latest Docker images without restarting anything. Use this to pre-download an update before applying it.

freeschema pull
# then apply:
freeschema restart

freeschema update

Updates both the CLI and the Docker images, then restarts all services.

freeschema update

What it does:

1. Runs npm install -g freeschema@latest
2. Runs docker compose pull
3. Runs docker compose up -d

freeschema down [-v]

Removes containers. Add -v to also delete all data volumes.

Warning: -v permanently deletes all stored data.

freeschema down       # remove containers only
freeschema down -v    # remove containers + all persistent data

freeschema setup-credentials

Logs in as admin, generates a new CLIENT_SECRET, and writes CLIENT_ID and CLIENT_SECRET to .env. Then restarts node-server, node-cache-server, log-server, and nginx-server to apply the change.

Run this if the automatic credential step during start timed out, or to rotate credentials.

freeschema setup-credentials
# prompts for admin email and password

freeschema db

Database management subcommands.

freeschema db seed

Places a SQL file into seed-db/. MySQL applies every file in that directory automatically on first boot when using --local-db.

freeschema db seed --url  https://example.com/data.sql
freeschema db seed --file ./my-export.sql

| Flag | Description | |---|---| | --url <url> | Download a .sql file from a URL into seed-db/ | | --file <path> | Copy a local .sql file into seed-db/ |

freeschema db backup [file]

Dumps freeschema_db to a .sql file using mysqldump. Requires the MySQL container to be running.

freeschema db backup                         # → backup-2026-05-21T10-30-00.sql
freeschema db backup ./exports/snapshot.sql  # custom output path

freeschema db restore <file>

Restores freeschema_db from a .sql file. Requires the MySQL container to be running.

freeschema db restore backup-2026-05-21T10-30-00.sql

freeschema --version

Prints the installed CLI version.

freeschema --version   # e.g. 1.0.29
freeschema -v

Directory Structure

After running freeschema init your project directory will look like this:

my-freeschema/
├── .env                        # main configuration (DB, JWT, MQTT, SMTP…)
├── .env.frontend               # frontend env vars (CORS origin, API URLs)
├── .env.example                # reference copy — never edited by the CLI
├── .env.frontend.example       # reference copy — never edited by the CLI
├── docker-compose.yml          # service definitions
├── my_custom.cnf               # MySQL tuning options
├── nginx/
│   ├── nginx.conf.template     # reverse-proxy config (routing, CORS)
│   ├── vccs-app.conf           # vccs-app nginx config
│   └── wico-app.conf           # wico-app nginx config
├── mosquitto/
│   └── config/
│       ├── mosquitto.conf      # MQTT broker config
│       └── password.txt        # hashed MQTT credentials (auto-generated)
└── seed-db/                    # SQL files applied to MySQL on first boot
    └── coredb.sql              # downloaded during init or via `db seed`

Environment Variables

.env — Core Configuration

| Variable | Description | Default | |---|---|---| | JWT_SECRET | Signs auth tokens — auto-generated by init | (random hex) | | DB_MODE | local (Docker MySQL) or external | local | | DB_HOST | Database hostname | mysql-server | | DB_PORT | Database port | 3306 | | DB_USER | Database username | freeschema | | DB_PASSWORD | Database password | Freeschema@123 | | DB_DATABASE | Main database name | freeschema_db | | DB_SESSION_DATABASE | Session database name | sessions_db | | MYSQL_PORT | Host port exposed by the MySQL container | 3308 | | MYSQL_ROOT_PASSWORD | MySQL root password | Admin@<DB_PASSWORD> | | MQTT_HOST | MQTT broker hostname | mqtt-broker | | MQTT_PORT | MQTT broker port | 1883 | | MQTT_USERNAME | MQTT username | freeschema | | MQTT_PASSWORD | MQTT password | freeschema | | NGINX_PORT | Host port for the Nginx reverse proxy | 80 | | CLIENT_ID | Admin entity ID — set by setup-credentials | (auto) | | CLIENT_SECRET | API secret — set by setup-credentials | (auto) | | SMTP_HOST | SMTP server hostname | (empty) | | SMTP_PORT | SMTP server port | 587 | | SMTP_USERNAME | SMTP login / from address | (empty) | | SMTP_PASSWORD | SMTP password | (empty) | | SMTP_FROM_ADDRESS | From address for outbound emails | (empty) | | ASPNETCORE_ENVIRONMENT | .NET environment (Production or Development) | Production |

Services

The Docker Compose stack includes these services:

| Service | Description | Internal Port | |---|---|---| | wico-server | Core .NET API | 7000 | | access-control-server | Access control / permissions API | 7000 | | node-server | Node.js middleware layer | 5000 | | node-cache-server | Caching layer | 5000 | | log-server | Log aggregation service | 5000 | | nginx-server | Reverse proxy (public entry point) | 80 | | wico-app | Wico frontend (SPA) | 80 | | vccs-app | VCCS frontend (SPA) | 80 | | mysql | MySQL 8.0 database (profile: local-db) | 3306 | | mqtt-broker | Eclipse Mosquitto 2.0 (profile: local-mqtt) | 1883 |

URL Routing (via Nginx)

| Path prefix | Routes to | |---|---| | /api/v1/… | node-server | | /api/… | wico-server | | /wico-api/api/v1/… | node-server | | /wico-api/api/… | wico-server | | /wico-api/… | wico-server | | /node-api/… | node-server | | /cache-api/… | node-cache-server | | /log-api/… | log-server | | /access-control-api/… | access-control-server | | /socket | node-server (WebSocket) | | /wico/… | wico-app | | /vccs/… | vccs-app | | / | wico-app (catch-all, also works if /wico is not set up on a custom root) |

Common Workflows

Fresh local install:

mkdir my-app && cd my-app
freeschema init
freeschema start --local-db --local-mqtt

Connect to an external database and MQTT broker:

mkdir my-app && cd my-app
freeschema init        # choose "External" for DB and MQTT
freeschema start

Load your own data on first start:

freeschema db seed --file ./export.sql
freeschema start --local-db

Rotate API credentials:

freeschema setup-credentials

Check what is running:

freeschema status
freeschema logs wico-server

Update to the latest version:

freeschema update

Back up and restore the database:

freeschema db backup ./backup.sql
freeschema db restore ./backup.sql

Full teardown including all data:

freeschema down -v

License

MIT