---

Open source game server with authentication, users, lobbies, server scripting and an admin portal.

Game + Backend = Gamend

---

Discord | Elixir Docs | API Docs | Guides | Starter Template | Architecture | Deployment Tutorial | Scaling Article

To start your server:

• Run mix setup to install and setup dependencies.

Now you can visit localhost:4000 from your browser.

Authentication

This application supports two authentication methods:

Browser Authentication (Session-based)

Traditional session-based authentication for browser flows:

• Email/password registration and login
• Discord OAuth
• Apple Sign In
• Google OAuth
• Steam OpenID
• Facebook OAuth
• Session tokens stored in database
• Managed via cookies and Phoenix sessions

API Authentication (JWT)

Modern JWT authentication using access + refresh tokens (industry standard):

Token Types:

• Access tokens: Short-lived (15 minutes), used for API requests
• Refresh tokens: Long-lived (30 days), used to obtain new access tokens

Users

User management:

• Multiple sign-in flows supported: Email/password, device tokens (SDK), and OAuth (Discord / Google / Facebook / Apple).
• Per-user profile metadata as JSON
• Account lifecycle: registration, login, password reset, and account deletion endpoints.

Friends

Social features:

• Friend requests with accept / reject / block flows.

Lobbies

Matchmaking and lobbies:

• Host-managed behavior, max users, hidden/locked states, and password protection.
• Public APIs are provided for listing, creating, joining, leaving, updating and kicking.

Server scripting (Elixir)

Extendable server behavior:

• Hooks on server events (eg. on_user_login, on_lobby_created)

Client SDK

• Javascript SDK
• Godot SDK

Elixir SDK

The sdk/ folder contains stub modules that provide IDE autocomplete and documentation for custom hook scripts. When building your own Starter Template, add the SDK as a dependency:

# mix.exs
defp deps do
  [
    {:game_server_sdk, github: "appsinacup/game_server", sparse: "sdk"}
  ]
end

Example hook with autocomplete:

defmodule MyApp.Hooks do
  use GameServer.Hooks

  @impl true
  def after_user_login(user) do
    # IDE autocomplete works for user fields and Accounts functions
    GameServer.Accounts.update_user(user, %{
      metadata: Map.put(user.metadata, "last_login", DateTime.utc_now())
    })
    :ok
  end
end

To regenerate SDK stubs from the main project:

mix gen.sdk

How to deploy (Starter Template)

1. Fork this repo (or create a Dockerfile like this):

FROM ghcr.io/appsinacup/game_server:latest

WORKDIR /app

COPY modules/ ./modules/
COPY apps/game_server_web/priv/static/assets/css/theme/ ./apps/game_server_web/priv/static/assets/css/theme/
COPY apps/game_server_web/priv/static/images/ ./apps/game_server_web/priv/static/images/

# Build any plugins shipped in this repo (overlay) so they're available at runtime.
ARG GAME_SERVER_PLUGINS_DIR=modules/plugins
ENV GAME_SERVER_PLUGINS_DIR=${GAME_SERVER_PLUGINS_DIR}

RUN if [ -d "${GAME_SERVER_PLUGINS_DIR}" ]; then \
		for plugin_path in ${GAME_SERVER_PLUGINS_DIR}/*; do \
			if [ -d "${plugin_path}" ] && [ -f "${plugin_path}/mix.exs" ]; then \
				echo "Building plugin ${plugin_path}"; \
				(cd "${plugin_path}" && mix deps.get && mix compile && mix plugin.bundle); \
			fi; \
		done; \
	else \
		echo "Plugin sources dir ${GAME_SERVER_PLUGINS_DIR} missing, skipping plugin builds"; \
	fi

2. Go to fly.io and deploy (select the forked repo).
3. Set secrets all values in .env.example. Run locally fly secrets sync and fly secrets deploy (in case secrets don't deploy/update).
4. Configure all things from Guides page.
5. Monthly cost (without Postgres) will be about 5$.

Run locally

To run locally using Elixir:

1. Configure the .env file (copy .env.example to .env).

2. Then run:

./start.sh

Run locally (Docker Compose)

To run with single instance, run:

docker compose up

To run multi instance with 2 instances, nginx load balancer, PostgreSQL database, Redis cache, run:

docker compose -f docker-compose.multi.yml up --scale app=2

Git hooks

To install precommit hooks, run:

	bin/setup-git-hooks

To skip, run:

	SKIP_PRECOMMIT=1 git commit