A mod to distribute a modpack to your friends, bypassing loaders like CurseForge
  • Java 54.5%
  • TypeScript 36.3%
  • JavaScript 5.2%
  • HTML 1.9%
  • CSS 1.7%
  • Other 0.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Dion Vos b609f75206
All checks were successful
CI / Docker image builds (push) Has been skipped
CI / Mod (Fabric + NeoForge jar) (push) Successful in 4m7s
CI / Server (push) Successful in 47s
Docker image / Build and publish image (push) Successful in 14m33s
Release / Build, sign and publish the mod jar (push) Successful in 4m15s
Merge pull request 'Versie kiezen werkt voor Git-mods (0.4.4-alpha)' (#19) from claude/git-version-switch into main
2026-10-18 13:37:25 +00:00
.forgejo/workflows Keep every ManageMC server on the newest release 2026-10-15 18:00:12 +02:00
.github/workflows
deploy/kubernetes Keep every ManageMC server on the newest release 2026-10-15 18:00:12 +02:00
docker Keep every ManageMC server on the newest release 2026-10-15 18:00:12 +02:00
mod Let the version picker switch Git mods to another release 2026-10-18 15:37:17 +02:00
server Let the version picker switch Git mods to another release 2026-10-18 15:37:17 +02:00
.dockerignore
.gitignore
docker-compose.yml Keep every ManageMC server on the newest release 2026-10-15 18:00:12 +02:00
Dockerfile Keep every ManageMC server on the newest release 2026-10-15 18:00:12 +02:00
LICENSE
README.md Keep every ManageMC server on the newest release 2026-10-15 18:00:12 +02:00

ManageMC

Keep modpacks in sync for a group of friends and their servers, without anyone updating jars by hand.

  • ManageMC server: one Docker container with a web interface. Create modpacks, upload jars or add mods from Modrinth and CurseForge, and install updates with one click. Every pack gets its own link, e.g. https://mc.example.com/pack/my-test-pack.
  • ManageMC mod: one jar for Fabric and NeoForge, Minecraft 1.21.1 and newer. On first start ManageMC asks for the pack link in a full-window screen inside Minecraft; from then on it keeps the instance's mods identical to the pack and shows download progress (with an estimate of the time left) over the pack's background image. The game always starts, even when a pack mod does not fit the Minecraft version: ManageMC leaves such mods out instead of letting the loader stop. It detects whether it runs on a client or a dedicated server and installs only the mods for that side.
 admins ──(web UI)──► ManageMC server ──(pack link)──► players & Minecraft servers
                             │    ▲
                             ▼    │ search, updates (hash-verified)
                        Modrinth · CurseForge

Running the server

You need a Linux server (VPS) with Docker. For automatic HTTPS, point a domain (e.g. mc.example.com) at the server and open ports 80 and 443.

Use the docker-compose.yml from this repository (it also keeps ManageMC up to date, see Always the newest version):

mkdir managemc && cd managemc
curl -O https://git.vos.je/Bewerkt/ManageMC/raw/branch/main/docker-compose.yml
mkdir docker && curl -o docker/auto-update.sh https://git.vos.je/Bewerkt/ManageMC/raw/branch/main/docker/auto-update.sh
docker compose up -d
docker compose logs managemc        # shows the one-time setup code

Without Compose it also runs with docker run -d --name managemc --restart unless-stopped -p 80:80 -p 443:443 -v managemc-data:/data git.vos.je/bewerkt/managemc:latest, but then you have to install every new release yourself.

Then open http://<your server's IP> and complete the setup:

  1. Enter the setup code from the log. Only someone with access to the server can claim it.
  2. Create your admin account.
  3. Enter the address players use (e.g. mc.example.com) and choose how HTTPS works:
    • Automatic HTTPS (recommended): the built-in Caddy gets a free Let's Encrypt certificate for exactly that address.
    • My own reverse proxy: nginx, Traefik, Cloudflare Tunnel… handle HTTPS. Point it at port 8080 of the container (-p 8080:8080) and leave out ports 80/443.
    • Plain HTTP: only for a local network or testing.

Everything is stored in the database inside /data, nothing goes in config files or environment variables. You can change it all later under Settings.

Storage location. All data (database, jars, certificates) lives in /data. To use a specific folder or disk, mount it there, e.g. -v /mnt/storage/managemc:/data. Back up that folder and you have backed up everything.

Several instances. Run the image again with a different domain and data folder, for example for another group of friends.

Locked out? docker exec -it managemc managemc-user reset-password <name>

The image is published to the container registry of the Forgejo at git.vos.je (see Building on Forgejo) and can be pulled without logging in.

Always the newest version

ManageMC is a platform: every ManageMC server, every player and every Minecraft server runs the newest release. Nobody can stay on an old version or pick one.

  • The ManageMC mod (players and Minecraft servers) updates itself from the signed releases on git.vos.je; see Building on Forgejo.
  • The ManageMC server (this image): :latest is always the newest release.
    • Docker Compose: the updater service in docker-compose.yml checks every 15 minutes and recreates the container with the new image. Your data is kept.
    • Kubernetes: with MANAGEMC_RESTART_TO_UPDATE=1 (set in the example manifest) ManageMC restarts itself when a new release is out, and Kubernetes pulls the new image (imagePullPolicy: Always).
    • Anything else: the admin panel announces a new release. A day later it pauses until the server is updated. Players keep playing and syncing in the meantime.

Creating a pack

  1. Under Packs, create a pack: name, Minecraft version and loader. The link is derived from the name: "My Test Pack" becomes https://mc.example.com/pack/my-test-pack. Under Pack settings, give it an icon (PNG/JPEG), a short description and optionally a background (a large image, e.g. a 1920×1080 screenshot of your world, max 8 MB). The icon and description show on the overview, the pack page and in the ManageMC screen in Minecraft; the background fills that screen as soon as a player connects, and tops the pack page. Without a background, a blurred version of the icon is used.
  2. Add mods:
    • Search Modrinth/CurseForge or paste a project link. Only versions for the pack's Minecraft version and loader are offered, and required dependencies are added too.
    • Upload jars (drag and drop). Uploads are looked up on Modrinth/CurseForge by hash, so they still get update checks when they come from there. Uploading a newer version of a mod replaces it.
  3. Per mod: side (client / server / both), enable/disable, remove.
  4. Optional: under Resource packs, upload resource packs (.zip), and under Servers, add the multiplayer servers of your group (name + address such as mc.example.com or mc.example.com:25565). See Resource packs and servers.
  5. Check for updates and Update all whenever you like. Players get the changes on their next start.

Importing an existing pack

Under Packs → Import pack, choose one of:

  • a Modrinth pack (.mrpack, e.g. exported from Modrinth App or Prism Launcher);
  • a CurseForge export (.zip from the CurseForge app: Export profile). This needs a CurseForge API key (Settings);
  • a zip of a mods folder. Choose the Minecraft version and loader yourself; the jars are looked up on Modrinth/CurseForge like normal uploads.

A new pack is created with the pack's name, Minecraft version and loader, and the mods are added in the background while the dialog shows the progress. Mods that come from Modrinth or CurseForge keep receiving update checks. Jars bundled in the pack's overrides folder are imported as uploads. Configs and shaders are not imported. Forge and Quilt packs are refused. The dialog lists every mod that could not be imported, e.g. a CurseForge mod whose author disabled third-party downloads; upload those jars by hand.

Tips:

  • Unlisted adds a random code to the link (/pack/my-test-pack-x7k2m9qp4r) so it cannot be guessed. New secret link replaces it if it leaked.
  • Duplicate pack copies a pack with all its mods, handy for preparing a Minecraft update without disturbing the current pack.
  • Opening a pack link in a browser shows a page with the mod list, the join steps and a download button for the ManageMC jar.
  • CurseForge search and updates need a free API key from console.curseforge.com (Settings). Modrinth works without a key.

Joining a pack

Player, the easy way (one-click instance): open the pack page and download the ready-made instance. It already has the right Minecraft version and loader, the ManageMC jar and a pre-filled ManageMC config with the pack link.

  • Modrinth App / Prism Launcher: download the .mrpack, then Modrinth App: + → Import from file; Prism Launcher: Add Instance → Import.
  • CurseForge app: download the .zip, then Create Custom Profile → Import.

Press Play. ManageMC downloads the mods itself, closes the game once and says when you can start again. The loader version is filled in automatically (latest stable Fabric/NeoForge) when a pack is created or its Minecraft version or loader changes; an admin can set a specific one under Pack settings. The instance buttons need the ManageMC jar to be bundled with the server.

Player, the manual way:

  1. Create an instance with the pack's Minecraft version and loader (Prism Launcher, CurseForge app, official launcher…).
  2. Put the ManageMC jar in the instance's mods folder. It can be downloaded from the pack page.
  3. Start the game. Instead of the main menu, ManageMC asks for the pack link: paste it, check the pack and click Join pack.
  4. ManageMC downloads the mods (with progress and the estimated time left) and restarts the game once to load them. Where the launcher does not allow a restart (e.g. the official launcher or an Android launcher), the game closes and you start it again yourself.

Later starts are silent when nothing changed. When the pack was updated, ManageMC already downloads it while Minecraft loads; the main menu then shows the progress and offers to restart (Later keeps playing with the current mods, which load the next time). ManageMC also works in Android launchers such as Pojav-based ones, since it no longer needs a separate desktop window.

Wrong loader or Minecraft version? When the pack needs another loader or Minecraft version than the instance runs (a player picked Fabric instead of NeoForge, or you moved the pack to a newer Minecraft), ManageMC offers to fix it:

  • Prism Launcher / MultiMC: ManageMC switches the instance itself (it edits the instance's mmc-pack.json, keeping a backup as mmc-pack.json.managemc-backup), installs the mods for the new version right away, and closes the game once. Prism downloads the new loader on the next start.
  • Other launchers: ManageMC explains what the instance needs and points to the ready-made instance on the pack page.

Dedicated server:

java -jar mods/managemc.jar join https://mc.example.com/pack/my-test-pack

Or set the environment variable MANAGEMC_PACK_URL (handy on hosts like Pterodactyl). Then start the server: on the first start it installs the mods and stops once. With a restart script or a host that restarts automatically, that happens by itself.

No restart at all (optional): sync before the game or server starts. In Prism Launcher / MultiMC, set this as the instance's pre-launch command (Settings → Custom commands):

"$INST_JAVA" -jar "$INST_MC_DIR/mods/managemc.jar" sync --game-dir "$INST_MC_DIR"

For a server start script: java -jar mods/managemc.jar sync --side server.

Mods that would stop the game from starting

Fabric and NeoForge refuse to start when a mod is made for the other loader or needs a mod that is missing (on Fabric that is often Fabric API). That happens before ManageMC runs, so a player would be stuck even after you fix the pack. ManageMC therefore checks every jar's declared dependencies (including mods bundled inside other jars) and leaves such mods out of what players receive until the pack is complete. The Mods tab then shows what is wrong, with Add from Modrinth / Choose Fabric version buttons and Fix automatically, which switches mods to the pack's loader and adds missing dependencies from Modrinth. Adding a mod from Modrinth also adds dependencies its jar needs but the platform does not list. Version requirements are not checked, only whether a dependency is present.

Testing changes before players get them

Turn on Test changes before players get them above a pack's tabs. From then on, everything you change (mods, versions, resource packs, servers, Minecraft and loader version) goes to a secret test link first, e.g. https://mc.example.com/pack/my-pack/test/<secret>. Join that link in a separate test instance (or download its ready-made instance from the test link's page), play, and when everything works press Publish to players. The card lists what is waiting: added, changed and removed mods, resource packs and servers. Players keep the published version meanwhile, including the old jar files.

  • Name, description, icon and background are not part of a release; players always see the latest ones.
  • New test link replaces the secret; testers need to join the new one. Wrong test links count towards the same lookup limit as unknown pack links.
  • Turning the option off gives players every waiting change right away.

Resource packs and servers

Players get these on every client (dedicated servers ignore them):

  • Resource packs are downloaded into the instance's resourcepacks folder, hash-verified like jars. A pack marked On for players is switched on automatically the first time a player receives it. After that the player decides: if they turn it off in Minecraft, ManageMC leaves it off, also when you upload a new version (the new file takes over the old one's on/off state). The order in the admin UI is the priority: the top pack is applied on top. Removed packs are deleted from the players' folders again. A player's own file with the same name is moved to .managemc/replaced-resourcepacks/, never deleted.
  • Servers appear at the top of the multiplayer list, in the order of the admin UI. Renaming or removing a server in the admin UI updates the players' lists. Servers players added themselves, including one with the same address they had before, are never changed.

On NeoForge, Minecraft has already read its settings when ManageMC runs, so a change in the resource pack selection closes the game once, like a mod change. On Fabric and in the pre-launch command it takes effect immediately.

Automatic server updates

A dedicated server with ManageMC keeps checking its pack while it runs (every minute). When the pack changes (with Test changes before players get them: when you press Publish), the server updates itself and brings its players along:

  1. It counts down 5 minutes and tells everyone in chat, again at 1 minute and 10 seconds:
    • players without ManageMC read that the server updates and that they install the new version themselves, with a button that opens the pack page;
    • players with ManageMC read that their game updates automatically and comes back, with a [Don't update me] button (/managemc autoupdate off, and on to undo). The choice is stored on the server.
  2. When the time is up, ManageMC players get an update command, then everybody is disconnected with a fitting message and the server stops after saving the worlds.
  3. The server comes back with the new pack:
    • under Docker, Kubernetes or Pterodactyl the host restarts it, and ManageMC installs the update on start;
    • otherwise ManageMC installs the update itself and starts the server again with the same command line. Its console output then goes to logs/managemc-console.log (the normal logs/latest.log still works); control it in-game, with RCON or by stopping the process.
  4. The game of every ManageMC player closes and starts again by itself, then installs the update in the ManageMC screen:
    • Prism Launcher / MultiMC: through the launcher, so its log window and accounts keep working;
    • other launchers: with the game's own command line (Linux, macOS and Windows);
    • if that is not possible, the player starts Minecraft again.
  5. On the next start the game shows “ is updating” while the server is still busy and joins it automatically as soon as it is back (Main menu stops waiting).

Operators can check with /managemc update and start right away with /managemc update now. In-game features need Fabric API on Fabric (practically every Fabric pack has it); without it ManageMC still syncs, only these features are off. Clients connect to servers without ManageMC and vice versa as usual. A client only restarts for a server of its own pack.

How syncing works

On every start the mod:

  1. downloads the pack's mod list (<pack link>/manifest.json);
  2. stops without changing anything if the pack is for another Minecraft version or loader than the running game;
  3. compares the list with the pack mods in .managemc/pack-mods/ (the pack's mods live there, not in mods; see below):
    • jars with the right content stay;
    • jars that are no longer in the pack are removed;
    • jars you put in mods yourself (minimap, shaders…) stay, unless they are another version of a pack mod. Those are moved to .managemc/disabled-mods/, never deleted;
    • missing mods are downloaded, from the official Modrinth/CurseForge CDN when possible (credits the author, saves your bandwidth), otherwise from your server. Every file must match its SHA-256 hash;
  4. applies nothing unless every download succeeded, so the pack is never half updated;
  5. restarts the game once if anything changed (mods are loaded before ManageMC runs) and starts it again by itself when it can (see below). A small helper process replaces jars the game still had locked (Windows) after the game closed. On a client the sync runs in the background while Minecraft loads; the game never waits for it.

If the server cannot be reached, the game starts with the mods it already has.

The game always starts. A loader refuses to start when a jar in mods needs another Minecraft version or a missing mod. That is why the pack's mods are kept out of mods and handed to the loader by ManageMC, which leaves out what does not fit:

  • Fabric: ManageMC puts the pack mods inside one container mod, mods/managemc-pack.jar. Fabric loads mods nested in another mod only if possible, so a mod for another Minecraft version (and any mod that needs it) is skipped instead of stopping the game.
  • NeoForge: ManageMC places a small mod locator plugin, mods/managemc-locator.jar, which NeoForge loads before it reads any mod. It adds the active pack mods (listed in .managemc/active-mods.txt) and leaves out mods that need another Minecraft or NeoForge version, plus the mods that need those. What was left out, and why, is logged and written to .managemc/skipped-mods.txt.

Both files are managed by ManageMC; don't remove them. A jar you put in mods yourself still has to fit, as always. Instances synced by an older ManageMC version are moved over automatically on the first start (without downloading the mods again).

config/managemc.json

Created automatically; normally you never edit it.

Key Default Meaning
packUrl "" The pack link; set by the first-start screen or join
enabled true false turns ManageMC off ("Don't ask again" sets this)
allowInsecureHttp false Allow http:// links (only on a trusted local network)
exitAfterUpdate true Close the game/server after changes so they load on the next start
continueWhenOffline true Start with the current mods when the server is unreachable
disableConflictingMods true Move self-installed jars that conflict with pack mods aside
disableUnmanagedMods false Strict mode: move every jar that is not in the pack aside
autoUpdateServer true Servers: watch the pack and restart for updates as described above
updateCountdownSeconds 300 Servers: warning time before an update (0–3600)
updateCheckIntervalSeconds 60 Servers: how often to check the pack (15–86400)
serverRestart "auto" Servers: auto, relaunch (ManageMC starts the server again) or exit (only stop; a restart script or host starts it)

Security

  • The instance can only be claimed with the setup code from the server log. Admin passwords are hashed with scrypt; sessions are HttpOnly/SameSite=Strict cookies; logins and setup attempts are rate limited; the UI has a strict Content-Security-Policy and CSRF protection.
  • Certificates are only requested for the configured address, so the built-in HTTPS cannot be abused for other domains.
  • Pack links are public on purpose; use Unlisted for packs that should stay private, and guessing attempts are rate limited. Only jars of enabled mods in that pack are served.
  • The mod verifies every jar by SHA-256 and size, only writes plain jar names inside mods/ and .managemc/, only follows redirects between the official CDNs, and refuses http:// unless you explicitly allow it.
  • Server-side downloads from Modrinth/CurseForge are verified against the hashes the platforms publish, and only their official CDNs are contacted.

Trying it locally

With Docker Desktop (Windows/macOS) or Docker on Linux:

git clone https://git.vos.je/Bewerkt/ManageMC.git && cd ManageMC
docker compose up -d                # the published image, kept up to date
docker compose logs managemc        # copy the setup code

To try your own changes, build the image with docker build -t managemc-dev . and run it with docker run (images built from source have no version and are never asked to update).

Open http://localhost, enter the setup code, create an admin and choose Plain HTTP with address localhost (or your computer's LAN IP, e.g. 192.168.1.20, so friends on your network can join). If port 80 is taken, change "80:80" to "8080:80" in docker-compose.yml and use localhost:8080. Because it is plain HTTP, ManageMC in Minecraft asks once to allow an http:// link. Stop it with docker compose down; the data stays in ./managemc-data.

Running on Kubernetes (k3s)

deploy/kubernetes/managemc.yml runs ManageMC behind Traefik with a cert-manager certificate for mc.vos.je, data on a hostPath (/var/lib/managemc), and the image from git.vos.je:

kubectl -n managemc create secret docker-registry regcred \
  --docker-server=git.vos.je --docker-username=Bewerkt --docker-password=<token with read:package>
kubectl apply -f deploy/kubernetes/managemc.yml
kubectl -n managemc logs deploy/managemc     # setup code

In the setup choose My own reverse proxy with address mc.vos.je: Traefik terminates HTTPS. To pick up a new image: kubectl -n managemc rollout restart deploy/managemc. Very large uploads (e.g. a zipped mods folder of several hundred MB) can hit Traefik's entrypoint read timeout; raise entryPoints.websecure.transport.respondingTimeouts.readTimeout if that happens.

Building on Forgejo

The repository lives at https://git.vos.je/Bewerkt/ManageMC. Forgejo runs .forgejo/workflows/ (and then ignores .github/workflows/, which stay for GitHub):

  • ci.yml: mod build and tests, server typecheck and tests, and a test build of the image, on every push.
  • docker.yml: builds the image; :main for every push to main (a development build), and :<version> plus :latest for v* tags, so :latest is always the newest release. It can also be started by hand from the Actions tab.

Releasing a version: tag a commit on main with v plus the version, e.g. v0.3.0-alpha, and push the tag (git tag v0.3.0-alpha && git push origin v0.3.0-alpha). Use semantic versions: 0.3.0-alpha, 0.3.0-beta.1, 0.3.0. The tag starts two workflows:

  • docker.yml publishes the image git.vos.je/bewerkt/managemc:0.3.0-alpha (and moves :latest to it), with a ManageMC jar of that version inside. ManageMC servers pick it up by themselves;
  • release.yml builds the jar, signs it with the release key and publishes it as a release here. Players and Minecraft servers pick that up by themselves.

If a tag push does not start them, run both by hand on the tag in the Actions tab.

The mod updates itself. ManageMC is a platform: every player and every Minecraft server always runs the newest release, and nobody can opt out or pin a version. On every start ManageMC checks the releases on git.vos.je; a newer jar is downloaded, checked against the release key's signature (whose public half is built into the mod) and against its own version number, and swapped in for the running jar under the same file name. It loads on the next start; on Windows the swap happens right after the game closes. The release private key is the repository secret MANAGEMC_SIGNING_KEY; keep a copy offline. Without it no update can be published, and a new key means every installation has to be updated by hand once.

Images are built with Kaniko, so the runner needs no Docker daemon or privileged containers; it also works for runners in Kubernetes. Once:

  1. Actions on: repository Settings → Units → Actions (and Actions enabled for the instance).
  2. A runner: register a forgejo-runner with the label docker (e.g. docker:docker://node:20-bookworm). Without one, workflows stay "waiting".
  3. A token for the registry: create an access token for Bewerkt with the scope write:package, and add it as repository secret REGISTRY_TOKEN (Settings → Actions → Secrets).
  4. Push to main, or start Docker image by hand in the Actions tab.

Development

cd mod && ./gradlew build          # universal jar in mod/build/libs (runs the tests)
cd server && npm ci && npm test    # server tests
cd server && npm run dev           # server with auto-reload on http://localhost:8080
docker build -t managemc .        # the complete image

Layout:

  • mod/src/main: loader-independent core (config, manifest validation, sync planning, downloads, the client sync session and its views, CLI).
  • mod/game-shared, mod/game-fabric, mod/game-neoforge: in-game features compiled against Minecraft, including the ManageMC screen.
  • mod/neoforge-locator: the NeoForge mod locator plugin, embedded in the universal jar.
  • mod/src/fabric, mod/src/neoforge: thin entry points per loader. NeoForge uses reflection so one jar works across NeoForge versions.
  • server/src: Express API, SQLite storage, Modrinth/CurseForge integrations. server/public: admin UI.
  • docker/: Caddy configuration and the container entrypoint.

Roadmap

  • Automatic instance switching for more launchers. Prism Launcher and MultiMC instances already switch automatically; the official launcher, CurseForge app and Modrinth App get a message pointing to the ready-made instance instead.
  • Optional S3-compatible storage for the jars.