Skip to main content

Local Setup

This guide starts faynoSync on your machine so you can test application updates end to end: upload a build, publish it, and point your app's updater at it. No cloud account is needed — object storage is Garage, a lightweight S3-compatible server, preconfigured in the repository.

There are two ways to run it, and only a few steps differ between them — those steps have a tab for each:

  • Docker Compose: the API, MongoDB, Redis and Garage all run as containers. Nothing to install except Docker. Choose this to try faynoSync or to test your app's updates against it.
  • From source: MongoDB, Redis and Garage run in Docker Compose, while the API and the dashboard run from source with go run and yarn dev. Choose this to work on faynoSync itself. If you already run MongoDB, Redis and S3-compatible storage locally, you can use them instead of the containers.

Everything runs from the repository's own docker-compose.yaml and .env.example, so the configuration always matches the current release.

To deploy faynoSync on a server, see Production Deployment.

Requirements​

1. Clone the Repository​

git clone https://github.com/ku9nov/faynoSync.git
cd faynoSync

2. Start the Services​

docker compose up --build -d

The first start builds the API image from source and bootstraps Garage (layout, access key, buckets, public website access). It takes a few minutes; later starts are fast. The API starts once MongoDB, Redis and Garage report healthy.

3. Apply Database Migrations​

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

Run this again after pulling a newer version of the repository.

4. Start the API and Dashboard​

Nothing to do: the backend container is already running. The API is at http://localhost:9000 and serves the dashboard at http://localhost:9000/dashboard/.

5. Create the Admin Account​

Open the dashboard signup page — http://localhost:9000/dashboard/signup with Docker Compose, http://localhost:3000/dashboard/signup from source — and register. In the Secret Key field enter the API_KEY from .env.example — for the bundled configuration that is insecure-dev-api-key.

Or do the same through the API:

curl -X POST -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password", "api_key": "insecure-dev-api-key"}' \
  http://localhost:9000/signup

6. Check for an Update​

After you create an app and upload a version, any client can ask for updates:

curl "http://localhost:9000/checkVersion?app_name=myapp&version=0.0.1&owner=admin"

Response formats are described in Check Latest Version.

Services and Ports​

ServiceCompose serviceURL / portNotes
FaynoSync APIbackendhttp://localhost:9000Container with Docker Compose, go run from source
Admin Dashboardbackendhttp://localhost:9000/dashboard/Served by the API
Dashboard dev server—http://localhost:3000/dashboard/From source only (yarn dev)
MongoDBdblocalhost:27017
Rediscachelocalhost:6379Required: response cache, telemetry counters, TUF state, rate limits
Garage S3 APIs3http://localhost:3900Access key and secret in .env.example
Garage website endpoints3http://localhost:3902Serves public artifact links
Garage admin UIwebuihttp://localhost:3909User admin, password BjjctVsoSg4FKkT81VKt18

Public artifact links have the form http://cb-faynosync-s3-public.web.garage.localhost:3902/<path>. Browsers and curl resolve any *.localhost name to your machine, so these links open without editing /etc/hosts.

The configuration lives in the repository:

  • .env.example — API environment (storage, Redis, telemetry, reports, TUF); Docker Compose reads it directly and overrides only the service hostnames in the backend service of docker-compose.yaml
  • docker-compose/configs/garage.toml — Garage configuration
  • docker-compose/scripts/garage-entrypoint.sh — Garage bootstrap

See Environment Configuration for every variable. The credentials in these files are for local testing only — never reuse them on a machine reachable from a network. API_KEY and JWT_SECRET use insecure-dev-* placeholders: the API logs a warning about them on every start and refuses to start with them when GIN_MODE=release.

The bundled configuration runs the API with performance mode, telemetry, reports and TUF enabled, so every feature is available locally.

Running Tests​

The integration tests need MongoDB, Redis and Garage running. Run the whole suite — the tests share state and depend on each other, so running a single test with -run is not supported.

The API image ships the test binary. Wait until Garage finishes its bootstrap (docker compose logs s3 shows Garage bootstrap completed successfully.), then run:

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

Logs​

docker compose logs -f            # all services
docker compose logs -f backend    # API only

Stopping Services​

docker compose down       # stop, keep data
docker compose down -v    # stop and delete all data volumes

Troubleshooting​

  • Port is already allocated — another service uses one of the ports above. Stop it, or change the host side of the port mapping in docker-compose.yaml. From source, port 9000 is taken when the API container is running: stop it with docker compose stop backend.
  • docker compose up waits before starting the API — the API starts only after MongoDB, Redis and Garage report healthy, and Garage turns healthy once its bootstrap (layout, key, buckets) has finished. Check progress with docker compose ps and docker compose logs s3.
  • The API run from source cannot connect to MongoDB, Redis or S3 — check that .env exists in the repository root and the containers are healthy.
  • /dashboard/ on port 9000 returns 503 or shows an old UI — from source, the API serves the dashboard embedded at compile time. Run yarn build in dashboard/ and restart the API, or use the dev server on port 3000.
  • Rebuilding the API image is slow — with Docker Compose, every API change needs docker compose up --build. To work on faynoSync itself, run it from source.

Next Steps​