Deployment Overview

What this covers

This page helps you decide what to check before going live. For concrete Docker setup, read Docker Deployment.

Quick Routing

What you want to do	Where to go
Run it locally first	Getting Started
Deploy with Docker	Docker Deployment
Configure public URLs	Config and Keys
Diagnose launcher, skin, or join issues	Troubleshooting
Understand texture and uploaded-avatar persistence	Object Storage

Check Before Launch

Production deployment is not finished when the container starts. AsterYggdrasil must also be reachable by launchers, Minecraft clients, and servers, so public URLs must work from outside the host.

Before launch, verify:

• The site is reachable through an HTTPS domain.
• /api/yggdrasil returns metadata.
• The homepage / keeps the X-Authlib-Injector-API-Location response header.
• public_site_url or yggdrasil_public_base_url can produce client-reachable texture URLs.
• skinDomains covers the host used by texture URLs.
• The database, config.toml, and object storage backend are persisted or recoverable.

Recommended Path

1. Complete Getting Started locally for accounts, profiles, and textures.
2. Prepare a domain name and HTTPS.
3. Mount /data using Docker Deployment.
4. Configure public_site_url; use yggdrasil_public_base_url only when you need an advanced path or host override.
5. Log in with a real launcher and join a test server once.
6. Back up the database, config.toml, and object storage backend.

Public URLs Matter Most

Texture URLs are embedded in the Yggdrasil textures property. Clients must receive absolute URLs, for example:

https://skin.example.com/api/yggdrasil/textures/{hash}

If that address works only from the server host, launchers and Minecraft clients cannot load skins. In that case, check public URL and reverse proxy configuration first.

Multiple Instance Boundary

These docs cover one primary node and optional follower instances. Periodic maintenance, mail outbox dispatch, audit cleanup, and texture consistency checks should run on only one primary node.

[server]
start_mode = "primary"

Use follower mode for other instances. Do not run global cleanup tasks from multiple instances at the same time.

What to Back Up

Back up at least:

• Database.
• config.toml or equivalent secret/config records.
• Object storage backend. The local backend usually uses a path similar to data/storage; S3/MinIO deployments must back up bucket objects and matching config.

Restore the database and object storage as a set. Restoring only the database can produce missing objects; restoring only objects can produce orphan objects.