Local Deployment

This guide starts a complete FaynoSync stack 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.

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

Requirements

• Docker Engine with Docker Compose
• Git
• Free ports: 9000, 3000, 27017, 6379, 3900–3904, 3909

Quick Setup

1. Clone and start the stack

git clone https://github.com/ku9nov/faynoSync.git
cd faynoSync
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.

2. Apply database migrations

Once the containers are running, apply the migrations:

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

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

3. Create the admin account

Open the dashboard at http://localhost:3000/signup and register. In the Secret Key field enter the API_KEY from docker-compose/envs/backend.env — for the bundled configuration that is UHp3aKb40fwpoKZluZByWQ.

Or do the same through the API:

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

4. 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"

Services and Ports

Service	Compose service	URL / port	Notes
FaynoSync API	backend	http://localhost:9000	Built from source
Admin Dashboard	frontend	http://localhost:3000	Development mode
MongoDB	db	localhost:27017
Redis	cache	localhost:6379	Required: response cache, telemetry counters, TUF state, rate limits
Garage S3 API	s3	http://localhost:3900	Access key and secret in docker-compose/envs/backend.env
Garage website endpoint	s3	http://localhost:3902	Serves public artifact links
Garage admin UI	webui	http://localhost:3909	User 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:

• docker-compose/envs/backend.env — API environment (storage, Redis, telemetry, reports, TUF)
• 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.

Monitoring and Logs

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

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

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/services/*.yml.
• API container exits right after start — MongoDB or Redis was not reachable yet; the API needs both and exits without them. Run docker compose up -d again once they are up.
• Apple Silicon — the API is built natively for your machine; the dashboard image runs as linux/amd64 through emulation, which is slower to start but works.

Next Steps

• Docker Development — run only the dependencies in Docker and the API or dashboard from source
• Environment Configuration — all configuration variables
• Production Deployment — deploy FaynoSync with managed storage