User Documentation

What this app does

This panel lets you create, run, inspect, back up, restore, and delete Minecraft servers from a web interface. Each server is managed as its own Docker-based spawn with its own data folder, logs, mods folder, and backup history.

The app currently supports two server types:

• VANILLA for unmodded servers
• FORGE for modded Forge servers

From the UI you can create a server, start and stop it, recreate its container, edit server.properties, upload mods, send console commands, view logs, analyze logs, create backups, restore backups, and recover archived backups after a server has been deleted.

Quick Start

1. Open Home from the navbar.
2. Create a new server with a name, port, type, and version choices.
3. Open the new server page.
4. Wait for the status to become running.
5. Watch the logs until startup finishes and the server is ready.
6. Copy the connection address shown on the server page.
7. Join from Minecraft using vfontaine.ca:PORT.
8. Create a manual backup before making major changes.

Navigation and pages

The top navigation bar is available on all normal pages. It links to Home, Documentation, Archived Backups, and an external Report an issue page on GitHub.

Home page

The home page has two jobs:

• Create a new server
• Show the list of existing servers and their current container status

Create server form

The form accepts these values:

• Name - optional. If left blank, the app generates a random UUID-style name.
• Port - optional. If left blank, the app assigns the next available port in the allowed range.
• Type - choose FORGE or VANILLA.
• Minecraft version - accepts LATEST, X.Y, or X.Y.Z.
• Forge version - accepts LATEST, X.Y.Z, or X.Y.Z.W for Forge servers.

Validation rules

• Spawn names can only contain letters, numbers, hyphens, and underscores.
• Spawn names cannot contain path traversal characters such as .., /, or \.
• Spawn names must be unique.
• Existing spawn directories on disk are also blocked from reuse.
• Ports must be between 25565 and 25665.
• Ports already used by another spawn are blocked.
• If no free port remains in the allowed range, server creation fails.
• Only FORGE and VANILLA are accepted as server types.

Spawn list

Below the create form, the page lists existing spawns. Each spawn links to its detail page and shows a color-coded status:

• Green for running
• Yellow for transitional states such as created, restarting, removing, paused, or exited
• Red for other failure or unavailable states

Create form errors

If server creation fails validation, the page shows an error notification at the top and keeps the values you already entered so you can correct only the problem field.

Spawn detail page

The spawn detail page is the main working area for an individual server. It combines live status, connection information, mods, backups, logs, console access, and property editing.

Server info card

• Name - the spawn name used by this app.
• Status - automatically refreshed every few seconds.
• Port - the external game port players should use.
• Players Online - shown when the server responds to status queries.
• Connect - the game address plus a copy button.
• Type - FORGE or VANILLA.
• MC Version - the configured Minecraft version.
• Forge - the configured Forge version.
• Loaded Mods - number of files currently in the mods folder.
• Pending Del - appears when one or more mods were deleted from disk but the server has not yet been restarted to fully apply the change.

Main server actions

Connecting players

1. Open the spawn detail page.
2. Confirm the server status is running.
3. Copy the connection address shown in the server info card.
4. Give players the address in the form vfontaine.ca:PORT.
5. From Minecraft Java Edition, open Multiplayer and paste the address into the server entry.

The host portion of the address comes from the configured SERVER_CONNECTION_HOST environment variable. Players always use that host plus the spawn port.

Mods management

The mods section is available on every spawn page. It works best for Forge-oriented workflows.

What you can do

• See the current list of mod files in the server's mods folder
• Delete an existing mod file
• Add a single .jar mod file
• Replace the full mods folder by selecting a folder of .jar files

Add Single Mod

1. Choose one .jar file.
2. Click Add Mod.
3. The page shows live upload progress with percentage, transferred size, speed, and estimated time remaining while the file is being sent.
4. The file is saved into the mods folder.
5. The server performs a lightweight restart so the new mod is applied.

After the upload reaches 100%, the page switches to a processing state while the server applies the mod and restarts.

Replace All Mods

1. Choose a folder containing the mod files you want to use.
2. Click Replace Mods.
3. The page shows live upload progress with percentage, transferred size, speed, and estimated time remaining while the files are being sent.
4. The browser uploads the selected .jar files to a temporary server-side batch in smaller requests instead of sending the whole folder in one large request.
5. After all files are staged, the app commits the batch as one full mods replacement.
6. The app swaps the full mods folder in one step instead of deleting old mods one by one.
7. The app performs a lightweight server restart to apply the new set.

This flow is optimized for larger mod batches and is much faster when replacing packs with 100 or more mods.

The time estimate reflects the browser upload stage. After the upload reaches 100%, the page switches to a processing state while the server applies the new mods and restarts.

Delete a mod

1. Click Delete beside the mod file.
2. The file is removed immediately from disk.
3. The app records the mod as a pending deletion.
4. Restart or recreate the server to fully apply the removal.

Delete All Mods

1. Click Delete All Mods in the mods section.
2. Confirm the action in the dialog.
3. The app removes all current mod files from disk in one operation.
4. The app records those files as pending deletions.
5. Restart or recreate the server to fully apply the removal.

Backups on the spawn page

Each spawn keeps its own local backups. These are separate from the archived backups page.

Manual backups

• You can create a backup with an optional custom name.
• If you leave the name blank, the app shows and uses a timestamp-based name.
• Manual backups are saved in the spawn's own backups directory.
• The backup captures the spawn contents, excluding the backups folder itself.

Scheduled backups

• You can enable or disable daily backups per spawn.
• You can choose the daily backup hour and minute.
• You can choose how many days of backups to keep.
• The scheduler uses the app timezone America/Vancouver.
• The scheduler checks regularly and creates one daily backup per day when enabled.

Existing backups list

When backups exist, the spawn page shows a list with:

• backup filename
• whether the backup is Manual or Daily
• timestamp
• size
• restore action
• delete action

Restore a spawn-local backup

1. Click the restore button beside the backup.
2. Confirm the restore.
3. The current server is stopped.
4. The current data directory is removed.
5. The backup is extracted into the spawn directory.
6. The app rewrites the compose settings so the spawn keeps its current name, port, and configured versions.
7. The server is recreated and started again.

Archived Backups page

The Archived Backups page is for preserved backups that survive server deletion.

How backups get archived

• When you delete a spawn, the app tries to archive the latest available backup first.
• If a latest backup exists, it is copied into the root archived backups folder.
• Metadata is saved with the archived backup, including source server, server type, Minecraft version, and Forge version.

What the archived backups table shows

• backup file name
• source server
• server type
• Minecraft version
• Forge version
• creation timestamp
• file size

Restore an archived backup

1. Open Archived Backups.
2. Find the backup you want.
3. Optionally provide a new server name.
4. Click Restore.
5. The app creates a brand new spawn using the backup metadata.
6. If the requested name already exists, the app automatically chooses a unique variation.
7. The app assigns the next available port.
8. The backup is copied into that new spawn and restored into it.
9. If restore succeeds, you are redirected to the new spawn page.

Delete an archived backup

Use the delete button to remove the archived backup permanently. A confirmation modal is shown first.

Logs, log streaming, and AI analysis

The logs section on the spawn page is one of the most useful places for troubleshooting.

What you can do

• Analyze - request an AI-assisted explanation of the current logs
• Stream - toggle live log refresh on and off
• Refresh - manually reload the current log view
• Full - open a full-page log view

What to expect

• Streaming is enabled by default when you open a spawn page.
• The main page log area refreshes every few seconds while streaming is active.
• The app converts Docker log timestamps into the Vancouver timezone for display.
• If the server has not produced logs yet, the log area may show No logs available.

AI log analysis

• The Analyze button sends the current logs to the configured Gemini model.
• If Gemini is configured, the app shows a modal with a summary and likely issue details.
• If Gemini is not configured, the analysis action returns a configuration error instead of a summary.

Console commands

The console input on the spawn page lets you send commands directly to the running Minecraft container.

Examples include common administrative or gameplay commands such as:

• list
• say Server maintenance in 5 minutes
• time set day
• whitelist add playername
• save-all

Server Properties editor

The Server Properties section shows the contents of server.properties for the current spawn.

• Edit the text directly in the textarea.
• Click Update & Restart to save and recreate the container.
• If the file does not exist yet for a brand new server, the editor may initially be empty.
• This is normal for newly created servers before their first full startup finishes.

Full logs page

The full logs page opens a dedicated page containing the server logs in a monospace block. Use it when you want a larger reading area or want to copy a longer chunk of logs. This page is read-only.

Loading and confirmation behavior

• Long-running actions show a loading modal.
• Deleting a spawn opens a dedicated confirmation modal.
• Deleting an archived backup also opens a confirmation modal.
• Restoring or deleting a local spawn backup uses browser confirmation prompts.

Error pages

The app includes friendly error pages for missing pages and unexpected server errors.

• 404 - shown when the route does not exist
• 500 - shown when an unexpected server-side error occurs

These pages show status details and a block of technical information you can send to the app maintainer for support.

Both error pages also provide direct buttons back to Home and Documentation.

Troubleshooting guide

Problem: I cannot connect to the game server

1. Open the spawn page and verify the status is running.
2. Verify the connection address is exactly vfontaine.ca:PORT for your current deployment.
3. Verify you are using the correct spawn port, not just the web panel port.
4. Check the logs and wait for normal startup completion before testing again.
5. If the server was just created, give it time to download and initialize the selected version.
6. If player count is unavailable, the server may still be starting or failing to answer status queries.

Problem: The server status is running but players still cannot join

1. Check the logs for whitelist, authentication, mod mismatch, or startup errors.
2. Make sure the players are using a compatible client version.
3. For Forge servers, make sure players have the matching mod set.
4. Copy the address from the spawn page instead of typing it manually.

Problem: The server fails to start

1. Read the latest logs.
2. Use Analyze if Gemini is configured.
3. Check for Minecraft version and Forge version mismatch.
4. If mods were recently added, suspect dependency issues or incompatible versions first.
5. If needed, restore a known-good backup.
6. Try Re-create after correcting the configuration.

Problem: I uploaded mods and now the server crashes

1. Check the logs for missing dependencies, duplicate mods, or wrong game version messages.
2. Verify each uploaded mod is a .jar file.
3. Verify the modpack matches the selected Minecraft version and Forge version.
4. Remove the last added mods or restore a backup from before the change.

Problem: I deleted a mod but nothing changed

1. Check whether the spawn page shows Pending Del.
2. Restart or recreate the server so the deletion fully takes effect.

Problem: The logs page says no logs are available

1. The container may not be created yet.
2. The server may still be starting.
3. The container may have exited before producing useful output.
4. Try Refresh or Re-create.

Problem: Log analysis does not work

1. Confirm there are logs to analyze.
2. Confirm GEMINI_API_KEY is configured for the app.
3. Try again after the server has produced enough logs to analyze.

Problem: My server.properties editor is empty

1. If the server is brand new, let it finish its first startup.
2. Refresh the spawn page afterward.
3. If needed, recreate the server once and check again.

Problem: Restore failed

1. Check the spawn logs after the restore attempt.
2. If the restored world or mods are incompatible with the configured server type or versions, the server may not start.
3. Use archived backups to restore into a new server if you want to avoid disturbing the current live spawn.

Problem: I deleted a server and want it back

1. Open Archived Backups.
2. Look for the latest archived backup from that server.
3. Restore it into a new spawn.
4. If there is no archived backup, the deleted live files are no longer available through the app.

Problem: I cannot create another server

1. Check whether the name is already in use.
2. Check whether the port is already in use.
3. Check whether the requested port is outside 25565-25665.
4. Check whether all ports in the allowed range have already been assigned.
5. Check whether the version string format is valid.

Problem: I opened a broken link or invalid page

The app will show a 404 page with helpful navigation back to Home or Documentation.

Problem: The app shows an unexpected server error

1. Open the error page details.
2. Copy the status code and details block.
3. Include the action you were trying to perform.
4. Include the server name if the issue happened on a specific spawn.

Best practices

• Create a manual backup before changing mods, properties, or world-critical settings.
• After deleting mods, restart or recreate the server before assuming the change is active.
• Keep Forge, Minecraft, and mod versions aligned.
• Use archived backups for long-term recovery after deleting old servers.
• Use the logs first whenever a server behaves unexpectedly.