- Java 54.5%
- TypeScript 36.3%
- JavaScript 5.2%
- HTML 1.9%
- CSS 1.7%
- Other 0.4%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
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
|
||
| .forgejo/workflows | ||
| .github/workflows | ||
| deploy/kubernetes | ||
| docker | ||
| mod | ||
| server | ||
| .dockerignore | ||
| .gitignore | ||
| docker-compose.yml | ||
| Dockerfile | ||
| LICENSE | ||
| README.md | ||
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:
- Enter the setup code from the log. Only someone with access to the server can claim it.
- Create your admin account.
- 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):
:latestis always the newest release.- Docker Compose: the
updaterservice indocker-compose.ymlchecks 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.
- Docker Compose: the
Creating a pack
- 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. - 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.
- Per mod: side (client / server / both), enable/disable, remove.
- Optional: under Resource packs, upload resource packs (
.zip), and under Servers, add the multiplayer servers of your group (name + address such asmc.example.comormc.example.com:25565). See Resource packs and servers. - 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 (
.zipfrom the CurseForge app: Export profile). This needs a CurseForge API key (Settings); - a zip of a
modsfolder. 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:
- Create an instance with the pack's Minecraft version and loader (Prism Launcher, CurseForge app, official launcher…).
- Put the ManageMC jar in the instance's
modsfolder. It can be downloaded from the pack page. - Start the game. Instead of the main menu, ManageMC asks for the pack link: paste it, check the pack and click Join pack.
- 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 asmmc-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
resourcepacksfolder, 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:
- 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, andonto undo). The choice is stored on the server.
- 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.
- 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 normallogs/latest.logstill works); control it in-game, with RCON or by stopping the process.
- 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.
- 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:
- downloads the pack's mod list (
<pack link>/manifest.json); - stops without changing anything if the pack is for another Minecraft version or loader than the running game;
- compares the list with the pack mods in
.managemc/pack-mods/(the pack's mods live there, not inmods; see below):- jars with the right content stay;
- jars that are no longer in the pack are removed;
- jars you put in
modsyourself (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;
- applies nothing unless every download succeeded, so the pack is never half updated;
- 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=Strictcookies; 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 refuseshttp://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;:mainfor every push tomain(a development build), and:<version>plus:latestforv*tags, so:latestis 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.ymlpublishes the imagegit.vos.je/bewerkt/managemc:0.3.0-alpha(and moves:latestto it), with a ManageMC jar of that version inside. ManageMC servers pick it up by themselves;release.ymlbuilds 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:
- Actions on: repository Settings → Units → Actions (and Actions enabled for the instance).
- A runner: register a forgejo-runner with the label
docker(e.g.docker:docker://node:20-bookworm). Without one, workflows stay "waiting". - A token for the registry: create an access token for
Bewerktwith the scopewrite:package, and add it as repository secretREGISTRY_TOKEN(Settings → Actions → Secrets). - 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.