Skip to content
ku9novPublic

About

Self-hosted, open-source update server for desktop apps (Velopack, Electron, Tauri, native). Own your release pipeline: version metadata, stable/beta/nightly channels, S3 artifacts, simple checkVersion API.

Topics

Resources

Contributing

Security policy

Stars

159 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

626 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

FaynoSync

a-github-banner-for-faynosync-featuring

OpenSSF Best Practices Documentation Docker Pulls GitHub Release Docker Compose Test


Self-hosted update server for desktop apps β€” your release pipeline, fully under your control.

⚑ Quickstart (<5 min)

Spin up the API with MongoDB, Redis, and a preconfigured S3-compatible storage (Garage) β€” no cloud account required:

git clone https://github.com/ku9nov/faynoSync.git
cd faynoSync
docker compose up --build                                   # API + MongoDB + Redis + Garage + Dashboard
docker compose exec -T backend /usr/bin/faynoSync migrate up # run after the stack is healthy

The API is now live at http://localhost:9000. Check for an update from any client:

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

Upload builds and manage versions via the dashboard served by the API at http://localhost:9000/dashboard/ or the REST API. Full setup, env vars, and self-build instructions are below.


πŸ“– Overview

faynoSync is a self-hosted, open-source API server for managing and updating cross-platform desktop applications (Windows, macOS, Linux). It enables automatic and on-demand updates for client software, making it easy to deliver new versions to users through a customizable update workflow.

The server allows developers to upload application builds to S3, set version metadata, and expose a simple REST API for clients to check for updates. When a client queries the API, it receives version information and a download URL if an update is available.

faynoSync supports both background updates and manual update prompts, depending on how the client integrates with the API. This gives developers full control over how and when updates are delivered to end-users.

It’s ideal for managing updates in Electron apps, native desktop applications, or any cross-platform software where you want full control over versioning, distribution, and update channels (e.g. stable, beta, nightly).

demo


πŸ› οΈ Supported Technologies

Category Technology Description
API Framework Go (Golang) Main application server built with Go
Database MongoDB Primary database for storing application metadata, users, and configurations
Cache & Performance Redis Required. Caching, statistics, TUF task state, rate limits
Updaters electron-builder Update feeds for Electron apps (auto-generated latest*.yml / latest-mac.yml)
Tauri Updater for Tauri apps (signature-based verification)
Squirrel Update support for Squirrel.Windows and Squirrel.Mac
Velopack Cross-platform installer/updater framework
Sparkle macOS-only installer/updater framework
Manual Direct download without a framework-specific update feed
Storage S3-Compatible Supports multiple cloud storage providers:
AWS S3 Amazon Web Services Simple Storage Service
Garage Recommended local S3-compatible storage, used via the AWS SDK
MinIO Deprecated local S3-compatible storage option that still works but is no longer maintained
Google Cloud Storage Google Cloud Platform storage service
DigitalOcean Spaces DigitalOcean's S3-compatible object storage

πŸ“– Documentation Links


πŸ–₯️ Dashboard

  • The web dashboard lives in dashboard/ and is embedded into the API binary, which serves it at /dashboard/. Set DASHBOARD_ENABLED=false to turn it off.

πŸ“± Client Application Examples

You can find examples of client applications here.

πŸ”— Example Links

πŸ“‹ API Usage Template


πŸš€ Installation

To build this application from source, you will need Go and, for the embedded dashboard, Node.js with Yarn. Install Go from the official website.

πŸ“₯ Installation Steps

  1. Install Go: Download and install from golang.org

  2. Clone Repository: Once you have installed Golang, clone this repository to your local machine:

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

βš™οΈ Configuration

All settings are environment variables. .env.example lists every variable with a one-line description and working values for local development; the full reference is the Environment Variables Overview.

  • Running the API from source: cp .env.example .env. The API reads .env from its working directory, and environment variables take precedence.
  • Docker Compose reads .env.example directly and overrides only the service hostnames (see the backend service in docker-compose.yaml).

πŸ§ͺ Local Storage (Garage)

For local development the recommended storage is Garage with the aws storage driver: Garage is the S3-compatible backend, and uploads and downloads go through the AWS SDK. The Docker Compose setup creates the buckets and imports the credentials from .env.example automatically.

Garage admin UI is available at http://localhost:3909/ (user: admin, password: BjjctVsoSg4FKkT81VKt18).

The dashboard is available at http://localhost:9000/dashboard/. For hot reload while working on it, run yarn dev in dashboard/: it serves on http://localhost:3000/dashboard/ and proxies API requests to http://localhost:9000. Run yarn build there before go build to embed it into a binary you build yourself.


🐳 Docker Configuration

To build and run the API with all dependencies (Local Setup β€” Docker Compose), use the following command:

docker compose up --build

πŸ“¦ Running Migrations

You can run migrations using this command after docker compose up --build finishes:

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

πŸ§ͺ Running Tests

You can now run tests using this command after docker compose up --build finishes and the storage service becomes healthy:

docker exec -it faynoSync_backend "/usr/bin/faynoSync_tests"

πŸ”§ Development Setup

If you only want to run dependency services (for local development without Docker), use this command:

docker compose up -d db cache s3 webui

Naming the services starts only them (and their dependencies), so backend stays down and you can run the API and dashboard from source while MongoDB, Redis, and Garage stay containerized. docker compose down stops them as usual. Step-by-step guide: Local Setup β€” from source.


πŸ’» Usage

To use the auto updater service, follow these steps:

πŸ”¨ Build the Application

cd dashboard && yarn install && yarn build && cd ..
go build -o faynoSync .

Skipping the dashboard build still produces a working API, but /dashboard/ returns 503.

πŸš€ Start the Service

  1. Start API Server:
./faynoSync
  1. Run Migrations (after API health check):
./faynoSync migrate up
  1. Rollback Migrations (if needed):
./faynoSync migrate down

πŸ“€ Upload Your Application

  1. Upload your application to S3 and set the version number in the dashboard (/dashboard/) or using API. For large builds, skip the reverse proxy and upload straight to storage with presigned URLs: POST /upload/init β†’ PUT β†’ POST /upload/complete, see Presigned Uploads.

πŸ” Check for Updates

  1. In your client application, make a GET request to the auto updater service API, passing the current version number as a query parameter:
http://localhost:9000/checkVersion?app_name=myapp&version=0.0.1&owner=admin&channel=stable&platform=linux&arch=amd64

πŸ“‹ API Response

The auto updater service will return a JSON response with the following structure:

{
    "update_available": true,
    "update_url_deb": "https://<bucket_name>.s3.amazonaws.com/myapp-admin/stable/linux/amd64/myapp-0.0.2.deb",
    "update_url_rpm": "https://<bucket_name>.s3.amazonaws.com/myapp-admin/stable/linux/amd64/myapp-0.0.2.rpm",
    "changelog": "### Changelog\n\n- Added new feature X",
    "critical": false
}

Each artifact is returned as update_url_<ext> (update_url_dmg, update_url_deb, ...), or as update_url when the file has no extension. Response formats for every updater are in Check Latest Version.

πŸ”” User Notification

  1. In your client application, show an alert to the user indicating that an update is available and provide a link to download the updated application.

πŸ§ͺ Testing

πŸš€ Run End-to-End Tests

go test

πŸ”¨ Build Test Binary

go test -c -o faynoSync_tests

πŸ§ͺ Run Unit Tests

# Optional: set MONGODB_URL_TESTS for tests that require a MongoDB connection
# export MONGODB_URL_TESTS=mongodb://root:MheCk6sSKB1m4xKNw5I@localhost/cb_faynosync_db_tests?authSource=admin
go test ./server/... -race

πŸ“‹ Test Requirements

Test Descriptions

To successfully run the tests and have them pass, create the .env file from .env.example.

The tests verify the implemented API using a test database and an existing S3 bucket.


πŸ”„ Database Migrations

πŸ“¦ Install Migration Tool

Install migrate tool here.

πŸ†• Create New Migrations

cd mongod/migrations
migrate create -ext json name_of_migration

Then run migrations with the built-in command:

./faynoSync migrate up

πŸ”— Migration Tool Link


About

Self-hosted, open-source update server for desktop apps (Velopack, Electron, Tauri, native). Own your release pipeline: version metadata, stable/beta/nightly channels, S3 artifacts, simple checkVersion API.

Topics

Resources

Contributing

Security policy

Stars

159 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages