FlockSync 0.3.1-beta

FlockSync 0.3.1-beta

FlockSync connects your WoW Forever guild's in-game data to a guild management dashboard. This beta includes the in-game addons, Windows desktop sync app, and self-hosted web/API deployment package.

Supported game interface: WoW Forever, Interface 16001.

This is testing software, not a stable general-availability release. Back up your data before upgrading and report problems without including credentials or private account data.

What's new

• Choose Release, Beta, or Alpha update channels in the desktop app and web admin settings.
• See a small, non-blocking web/API update banner when a newer eligible server version is available.
• Receive addon update reminders once at initial character login—not repeatedly during play, UI reloads, or zone changes.
• Publish and download everything from one combined release. Each update checker compares its own component version, so unchanged components do not trigger false update notifications.
• Automatically create and verify a SQLite backup before server upgrades performed through the new guarded update script. Backup failure stops the upgrade.
• Added a repeatable packaging and release guide.

Included versions

Component	Version
Overall release	0.3.1-beta
FlockSync main addon	0.3.1-beta
FlockSync AppHelper	0.2.1-beta
Windows desktop app	0.2.1-beta
Web dashboard and API	0.2.1-beta

Different component versions are intentional. The overall release is a bundle, not a requirement that every component share a version.

Which download do I need?

Download	What it is / who needs it
FlockSync-Raider-Only.zip	Main in-game addon. This is all ordinary guild members need.
FlockSync-Addon-Bundle.zip	Main addon plus AppHelper. Intended for officers running desktop synchronization. Install this instead of the member ZIP, not in addition to it.
FlockSync-Setup-0.2.1-beta-x64.exe	Windows desktop installer for officers who upload guild data.
FlockSync-Portable-0.2.1-beta-x64.exe	Alternative Windows desktop build that runs without an installer. Choose this OR Setup.
FlockSync_Pi_Deploy.zip	Source and Docker configuration for administrators hosting the web dashboard and API. Not needed by ordinary players.
flocksync-release.json	Component-version manifest used by update checkers. Leave it attached to this release; players do not need to install or edit it.

GitHub's automatically generated “Source code” archives are not the packaged member addon or Windows application. Use the downloads listed above.

How FlockSync works

1. The main addon scans supported character data, including gear, roles, and guild-planning information.
2. Characters share updates through hidden guild addon messages.
3. Officer catchers aggregate guild data into their account's SavedVariables.
4. The officer's desktop app watches those files and uploads changes to the configured guild API using an authenticated officer/admin account.
5. The API stores the data, and the web dashboard provides guild roster and planning tools.
6. Server return data is written through AppHelper and loaded in-game. Officers can relay guild snapshots to members who do not run the desktop app.

WoW normally writes SavedVariables on logout or /reload, not continuously. Uploads and return data are therefore not an instant, live connection to the running game.

Installation

Guild members: main addon only

1. Exit WoW.

2. Download and extract FlockSync-Raider-Only.zip.

3. Copy the FlockSync folder directly into your game's Interface\AddOns directory.

4. Confirm the resulting layout is:

   Interface\AddOns\FlockSync\FlockSync.toc

   Do not leave an extra ZIP-name or bundle folder between AddOns and FlockSync.

5. Enable FlockSync in the character-selection AddOns list.

6. Log in and finish the first-time walkthrough. Choose your features, role/off-spec, and main character. Scanning and broadcasting remain paused until you finish onboarding.

Daily controls:

• /fs: daily-use features.
• /fs options: settings.
• Minimap left-click: features.
• Minimap right-click: settings.

Members do not need the desktop app or AppHelper just to broadcast character data. A web account is only needed to sign in to the dashboard.

Officers: addons and Windows sync app

1. Exit WoW.

2. Download FlockSync-Addon-Bundle.zip and extract both folders directly into Interface\AddOns:

   Interface\AddOns\FlockSync\FlockSync.toc
   Interface\AddOns\FlockSync_AppHelper\FlockSync_AppHelper.toc

3. Enable both addons in WoW.

4. Download either the desktop Setup executable or the Portable executable.

5. If upgrading, fully quit the old app using Quit FlockSync in its system tray menu first. Closing the window may only minimize it to the tray.

6. Install/run the new app.

7. Enter the API server URL provided by your guild administrator, such as https://guild.example.com. Do not add an /api suffix.

8. Sign in with an account assigned OFFICER or ADMIN by your server administrator. Registering an account does not automatically grant officer access.

9. Select your WoW installation directory and keep the desktop app running while playing.

10. Complete addon onboarding and use /reload or log out to write data for synchronization. Confirm the desktop app reports a successful sync.

Officer alts

Log in with a character whose guild permissions/rank qualify as an officer so FlockSync can recognize that guild for the WoW account. Other characters on that same WoW account can then act as catchers while in the same recognized guild.

This does not grant catcher status in unrelated guilds. Local Test Officer Mode is off by default and normally should remain off.

Loading returned server data

For the clearest return-trip test: log out of WoW, let the desktop sync complete, then log back in. AppHelper reads the returned SavedVariables when the game loads them. A /reload writes the game's existing in-memory SavedVariables before reloading, so do not assume an external file edit immediately replaces data already loaded in-game.

Dashboard users

Open the guild dashboard URL provided by your administrator and sign in or create an account if registration is available. Ask an administrator for officer access if your responsibilities require it.

The dashboard provides roster and gear views, availability, team planning, crafting/gear-goal tools, and role-restricted management features. Available controls depend on your account role.

Self-hosting the server: first installation

The deployment package contains the web dashboard, API, shared contracts, Docker build files, reverse-proxy configuration, and backup tooling. It does not contain a prebuilt Docker image, real credentials, or an existing database.

Requirements:

• A 64-bit Linux host, such as Raspberry Pi OS/Debian on a Raspberry Pi 5.
• Docker Engine and the Docker Compose plugin.
• Local storage for the live SQLite database. Do not place the live database on a NAS share.
• A writable backup directory, optionally on a mounted NAS.
• For the included public-access setup, a Cloudflare-managed hostname and Cloudflare Tunnel token.

1. Download FlockSync_Pi_Deploy.zip and extract it on the server. Open a terminal in its top-level FlockSync directory.

2. Create your production environment file:

   cp .env.production.example .env.production
   openssl rand -hex 32

3. Edit .env.production:

   • Set JWT_SECRET to a newly generated random secret.
   • Set INITIAL_ADMIN_EMAIL and a unique INITIAL_ADMIN_PASSWORD of at least 16 characters.
   • Set CLOUDFLARE_TUNNEL_TOKEN to your tunnel token.
   • Set NAS_BACKUP_PATH to your chosen existing backup directory.
   • Set GITHUB_REPOSITORY if using a different public release repository.

   Keep this file private. The initial admin is created only when the users table is empty; changing the environment password later does not reset an existing account.

4. Prepare database storage:

   mkdir -p data/sqlite
   sudo chown 1000:1000 data/sqlite

5. Prepare backups:

   • NAS: mount the share first, verify it is actually mounted, and confirm the backup container will have write access.
   • Local trial: create data/backups and set NAS_BACKUP_PATH=./data/backups.

   The configured destination must already exist. A directory existing at a NAS mountpoint does not prove that the NAS is mounted.

6. In Cloudflare Tunnel's public-hostname settings, route your chosen hostname to the HTTP service http://web:80.

7. Build and start the stack:

   docker compose --env-file .env.production up -d --build
   docker compose --env-file .env.production ps
   docker compose --env-file .env.production logs --tail 100 api web db-backup cloudflared

8. Open your own HTTPS hostname and sign in with the initial admin account. Verify /health at that hostname and test a desktop sync.

9. Give guild officers your hostname as their desktop API server URL and assign their web/API accounts the appropriate role.

The supplied Compose configuration does not publish host ports. Access through the configured tunnel, or deliberately configure your own reverse proxy/network exposure. Browser-only Cloudflare Access challenges can prevent desktop API calls; the desktop app does not implement Cloudflare Access service-token authentication.

Upgrading an existing server

1. Preserve your existing .env.production and data directory. Keep a separate secure copy of configuration.

2. Extract/select the new deployment source without overwriting those files or deleting data.

3. Confirm NAS_BACKUP_PATH points to an existing, writable destination. Verify the NAS is mounted if applicable.

4. From the deployed project directory, run:

   sh deploy/update-server.sh

5. Verify the result:

   docker compose --env-file .env.production ps
   docker compose --env-file .env.production logs --tail 100 api web

6. Test dashboard login and desktop synchronization.

The update script creates and verifies a consistent SQLite backup before rebuilding or restarting API/web containers. If backup fails, it stops the upgrade. Pre-update backups have unique filenames and are retained until manually removed.

Daily backups run separately and retain daily snapshots for 30 days. Backups contain sensitive guild/account data, including password hashes; restrict access.

Direct Docker rebuild/update commands bypass the guarded update script. Do not use docker compose down -v as an upgrade step. Do not restore a database over a running connection. A backup does not mean automatic rollback is implemented.

Update channels and reminders

• Release: stable builds only; this is the default.
• Beta: beta and stable builds.
• Alpha: alpha, beta, and stable builds.

Select Beta or Alpha to receive notices for this beta build. Changing channels does not automatically downgrade an installed version.

Desktop

Choose a channel in App Settings. Checks run shortly after startup and every six hours while the app is running. You can also check manually in settings or the tray menu.

An update banner opens the GitHub release page. Downloading and installation remain manual. Remind Me Later suppresses scheduled checks until the next full app launch; manual checks still work.

Web/API

Administrators select the channel in Admin Settings; the preference is saved per browser. Signed-in users see a small amber update notice when a newer eligible server version is available. The notice does not install updates or restart containers.

In-game addon

The addon cannot contact GitHub or CurseForge directly. It uses release information received through server/desktop sync and guild sharing.

It checks saved release information once at initial character login and prints at most one update message. Metadata received during play is saved for a later login. UI reloads and zone transitions do not trigger update notices.

Stable addon builds ignore previews. Beta builds can announce beta or stable versions; alpha builds can announce all three. Manage preview downloads through CurseForge. GitHub publication does not automatically upload the addon there.

No notice does not guarantee that you are current: offline or recently unsynced guilds may have stale or no release information.

Combined releases

The attached flocksync-release.json records each component's version. A newer overall release only triggers a component notice if that component has a newer eligible version. Unchanged components can be included again without causing false update notices.

Previously distributed desktop/server builds require an initial manual upgrade to this manifest-aware version. Update metadata and downloads must be publicly readable; signing into GitHub in a browser does not let the unauthenticated checker read private releases.

Reporting problems

Include the component/version, what you expected, what happened, and reproduction steps. Redact logs before sharing. Never attach passwords, JWTs, tunnel tokens, production environment files, private SavedVariables, or database backups.