Skip to main content

Local Development with faynoSync — Choose Your Path

· 8 min read
Serhii Kuianov
Serhii Kuianov
DevOps

Want to try a self-hosted update server before putting it anywhere near production? Or hack on faynoSync itself? Either way, you start with a local setup — and with faynoSync that takes a few minutes, not an afternoon.

There are two ways to run it locally: everything in Docker, or the Go API from source with only the dependencies in containers. This post shows both, explains what each service in the stack does, and covers the first steps once it's running.

Updated in October 2026

Local setups use Garage (S3-compatible) through the aws storage driver, and Redis is now a required service. Since v2.7.0 the dashboard is built into the API binary and served at /dashboard/ — there is no separate dashboard container or repository anymore. The steps below reflect the current setup.

What runs in the local stack​

Whichever option you pick, faynoSync needs the same pieces:

ServiceLocal portWhat it does
faynoSync API9000The update server itself: uploads, update checks, feeds, telemetry
Admin dashboard9000 (/dashboard/)Web UI for apps, channels, platforms, versions, tokens, TUF — served by the API. When you work on the dashboard itself, its dev server runs on 3000
MongoDB27017Stores apps, versions, channels, platforms, users
Redis6379Required — the API connects on startup and exits if Redis is unreachable. Also used by Performance Mode, rate limits and telemetry counters
Garage3900 (S3 API), 3902 (web)S3-compatible storage for your build artifacts and generated feeds
Garage web UI3909Browse buckets and objects

Garage plays the role that AWS S3 (or another S3-compatible provider) plays in production. faynoSync talks to it through the same aws driver it uses for real S3, so your local setup behaves like production instead of like a special case.

Option 1: Everything in Docker Compose 🐳​

Best for: trying faynoSync, testing the API, building an integration against it, or running the test suite without installing Go.

What You'll Need:​

Start the stack​

git clone https://github.com/ku9nov/faynoSync.git
cd faynoSync
docker compose up --build

This builds the API image and starts the API, MongoDB, Redis and Garage; the API also serves the dashboard. Local configuration comes from .env.example in the repository root, and Garage's credentials and buckets are imported automatically during container bootstrap.

When the stack is healthy, apply the database migrations from a second terminal:

docker compose exec -T backend /usr/bin/faynoSync migrate up

Check that the API is up:

curl http://localhost:9000/health
{"status":"healthy"}

The dashboard is now at http://localhost:9000/dashboard/.

Run the tests​

Wait until Garage finishes its bootstrap — docker compose logs s3 shows Garage bootstrap completed successfully. — then run the test suite inside the backend container:

docker compose exec -T backend /usr/bin/faynoSync_tests

The step-by-step version of this option, with every port and config file, is in the Local Setup docs (Docker Compose tab).

Benefits:​

  • 🚀 One command to a working stack
  • 🧩 Nothing installed on your machine except Docker
  • 🔄 Same setup on every machine
  • 🧪 Easy to run the full test suite

The trade-off: rebuilding the image after every code change is slow. If you're changing faynoSync's code, Option 2 is more comfortable.

Option 2: API and dashboard from source, dependencies in Docker 🖥️​

Best for: contributing to faynoSync, debugging the API, or anything where you want a fast edit-and-run loop.

What You'll Need:​

  • Golang 🐹 — Installation Guide
  • Node.js and Yarn — for the dashboard
  • Docker and Docker Compose — for MongoDB, Redis and Garage

Start only the dependencies​

docker compose up -d db cache s3 webui

Naming the services starts only them, so the backend container stays down. MongoDB, Redis and Garage stay in containers; the API and the dashboard run from source.

Already running MongoDB, Redis and S3-compatible storage on your machine? Skip this step and point .env at them instead — the Environment Variables Overview lists what to change.

Configure the environment​

cp .env.example .env

.env.example already holds working values for the containers above — MongoDB and Redis on localhost, the Garage S3 API on 127.0.0.1:3900, the Garage credentials and buckets. Nothing to edit for a local run. The Environment Variables Overview explains every variable.

Run faynoSync​

# First run and after schema changes
go run faynoSync.go migrate up

# Start the server
go run faynoSync.go --loglevel=debug

Roll back migrations with go run faynoSync.go migrate down.

Run the tests​

go test

The tests run against the real MongoDB, Redis and Garage from your containers — nothing is mocked — so a green run means your local environment is really wired up correctly. Always run the whole suite: the tests share state, so a single -run is not supported.

Benefits:​

  • ⚡ Fast development cycle
  • 🔧 Direct access to all components
  • 🧪 Easy debugging
  • 🔄 Quick code changes

Run the dashboard​

The dashboard code lives in the dashboard/ folder of the same repository. In a second terminal:

cd dashboard
yarn install
yarn dev               # http://localhost:3000/dashboard/, proxies the API on :9000

The dev server gives you hot reload, shares one origin with the API through its proxy, and sends the same Content Security Policy as production. The API on :9000 also serves a dashboard, but that one is embedded into the binary at compile time from the last yarn build — run yarn build and restart go run to check the production build.

The step-by-step version of this option is in the Local Setup docs (From source tab).

Which Option Should You Choose? 🤔​

Option 1: DockerOption 2: Go from source
Setup timeMinutesA bit longer (Go, Node.js)
Installed locallyDocker onlyDocker + Go + Node.js
Code change → runningRebuild the imageRestart go run; hot reload for the dashboard
Debugging the APILogs onlyFull debugger access
Best forTrying faynoSync, building integrations, CI-like test runsContributing, debugging, daily development

If you're evaluating faynoSync as an update server for your app, start with Option 1. You can switch to Option 2 later — MongoDB, Redis and Garage are the same containers either way.

First steps once it's running​

A fresh server is empty. To see an actual update check work:

  1. Register an admin. Open http://localhost:9000/dashboard/ (or http://localhost:3000/dashboard/ with the dev server) and sign up. The registration asks for the signup key — that's the API_KEY from your environment (.env.example in the Docker setup). If API_KEY is empty, signup is disabled.
  2. Create the basics. An application, a channel (for example stable), a platform and an architecture.
  3. Upload two versions. From the dashboard, or from the terminal with the faynoSync CLI — the same command later runs in CI.
  4. Check for an update, the same way your app will:
curl "http://localhost:9000/checkVersion?app_name=myapp&version=0.0.1&owner=admin"

If you'd rather follow a complete example end to end — build a real desktop app, upload it, install it, ship a delta update and roll it back — the self-hosted Velopack update server tutorial runs entirely on this local setup. For Electron apps, see How to Setup Auto Update for Electron App.

Troubleshooting​

The API exits right after start. Most often Redis isn't reachable. Redis is required, and the API exits if it can't connect. Check that the cache container is up and REDIS_HOST / REDIS_PORT match.

Uploads fail right after docker compose up. Garage may still be bootstrapping. Wait for Garage bootstrap completed successfully. in docker compose logs s3.

Sign up returns an error. The signup key must match API_KEY on the server. With an empty API_KEY, the /signup endpoint is disabled on purpose.

A port is already in use. Another service is already listening on one of 9000, 3000, 27017, 6379, 3900, 3902 or 3909. Stop it or change the port mapping in docker-compose.yaml.

What's Next? 🚀​

Once the local server works, these are good next reads:

How to try faynoSync?​

  1. Follow the Getting Started guide:
    👉 https://faynosync.com/docs/getting-started

  2. Create your app using the REST API or web dashboard:
    📦 API Docs: https://faynosync.com/docs/api
    🖥️ Dashboard UI: served by the API at /dashboard/, source in dashboard/

  3. Upload at least two versions of your application.

  4. Check for updates with this simple request:
    📡 /info/latest

If you find this project helpful, please consider subscribing, leaving a comment, or giving it a star, create Issue or feature request on GitHub.
Your support keeps the project alive and growing 💚