# Minecraft Modpacks

Packwiz-managed Minecraft modpacks used by the AGS Minecraft infrastructure.

The repository is the source of truth for both client and server modpack configuration. Packs are deployed through Gitea Actions and served as static Packwiz repositories for Pterodactyl.

## Packs

### Forever World

Long-lived NeoForge survival world with a deliberately conservative mod selection.

- Minecraft: 1.21.1
- NeoForge: 21.1.248
- Packwiz: managed
- Production: release-based

Development:

```text
https://mc.ahmza.com/forever/dev/pack.toml
```

Stable:

```text
https://mc.ahmza.com/forever/stable/pack.toml
```

### Creative Playground Server

`agsmc-playground` is a disposable creative superflat server that consumes the
Forever stable pack. It does not have an independent Packwiz publication
channel. Upcoming pack changes are validated on `agsmc-forever-staging` through
the Forever development endpoint.

## Repository Structure

```text
mc-modpacks/
├── .gitea/
│   └── workflows/
├── scripts/
│   └── build-site.sh
├── Dockerfile
├── sws.toml
├── forever/
│   ├── pack.toml
│   ├── index.toml
│   ├── mods/
│   ├── config/
│   ├── defaultconfigs/
│   └── README.md
└── deploy/
    └── kubernetes/
```

## Development Model

`main` represents the current development state.

Normal changes are committed directly to `main`:

```bash
git switch main

cd forever
packwiz update <mod>
packwiz refresh

git add .
git commit -m "Update <mod>"
git push
```

A push to `main` publishes the pack to its `dev` endpoint.

Production is **not** updated by normal commits.

### Branches

Branches are reserved for substantial or experimental work, for example:

```text
mc-26-migration
create-major-upgrade
worldgen-experiment
test-new-content-mod
```

Small mod updates and configuration changes do not require branches.

## Releases

Test the development pack before creating a release.

Forever World releases use annotated tags:

```bash
git tag -a forever-v1.0.1 -m "Forever World v1.0.1"
git push origin forever-v1.0.1
```

A release publishes an immutable copy to:

```text
/forever/releases/v1.0.1/
```

and promotes the same build to:

```text
/forever/stable/
```

Production Pterodactyl servers always consume the stable endpoint rather than individual release URLs.

### Versioning

Approximately follow semantic versioning:

| Version | Use |
|---|---|
| `v1.0.1` | Bug fixes, configs and routine mod updates |
| `v1.1.0` | New functionality or compatible mods |
| `v2.0.0` | Major Minecraft/modpack/world dependency changes |

Release tags are immutable. Never move or recreate an existing release tag.

## Deployment Flow

```text
                         Gitea
                           │
                     push to main
                           │
                           ▼
                    Gitea Actions
                           │
                           ▼
                /forever/dev/pack.toml
                           │
                           ▼
                    Staging Server
                           │
                         Test
                           │
                  forever-v1.x.x tag
                           │
                           ▼
                    Gitea Actions
                      ┌────┴────┐
                      ▼         ▼
                  releases/   stable/
                                │
                                ▼
                         Production Server
```

Packwiz is responsible for modpack contents and side filtering.

Pterodactyl is responsible for Java, server process management and resources.

Kubernetes/SWS provides static hosting for the published Packwiz repositories.
The publishing workflow runs [`scripts/build-site.sh`](../scripts/build-site.sh),
which exports committed Git revisions into the documented URL layout. Source
packs intentionally keep `no-internal-hashes = true`; the workflow runs
`packwiz refresh --build` only against the exported copies under `.build/site`
so the image contains installer-ready hashes without committing generated hash
churn. It then builds the multi-architecture image
`tea.ahmza.com/ahmza.com/mcpacks-site`.

The workflow finally commits that image's immutable OCI digest to
`apps/mcpacks/deployment.yaml` in the `ahmza.com/k8s-starter-pack` repository.
Argo CD notices that commit and performs the rollout; the workflow does not
hold Kubernetes credentials or change the cluster directly.

The publishing workflow uses two Gitea Actions repository secrets belonging
to `ci-bot`:

- `REGISTRY_TOKEN` can push packages owned by the `ahmza.com` organization
- `GITOPS_TOKEN` can read and write `ahmza.com/k8s-starter-pack`

Keeping these credentials separate ensures that the package token cannot modify
Git repositories and the GitOps token cannot publish packages.

The `latest` image tag exists only to bootstrap the first Argo CD sync and for
human inspection. Normal rollouts use the exact content digest recorded in the
GitOps manifest, making the running version auditable and rollback-friendly.

## Rollback

Release directories are immutable.

If a release causes problems, production can be pointed temporarily at an earlier release:

```text
https://mc.ahmza.com/forever/releases/v1.0.1/pack.toml
```

Do not rewrite an existing release or tag. Fix the issue on `main` and publish a new release.