Canary is an OpenTibia server emulator with a Docker stack for local testing

A server core with Lua scripts and datapacks

Canary is a free and open-source MMORPG server emulator for the OpenTibia community, written in C++20 and Lua, and it is a fork of the OTServBR-Global project. The repository layout shows what a server of this kind contains. There is the server core in `src/`, the Lua entry configuration in `config.lua.dist`, the database schema in `schema.sql`, and two data directories, `data-canary/` and `data-otservbr-global/`, which is the clearest sign of the fork's lineage, since the upstream dataset is kept alongside the project's own. Build configuration lives in `CMakeLists.txt`, `CMakePresets.json` and the `cmake/` directory, dependency management is vcpkg with a `vcpkg.json` and a `vcpkg-registry/` directory, and the tooling that turns a dataset into a running world sits in `tools/`. There is also a `metrics/` directory, a `Jenkinsfile`, a `GitVersion.yml` for versioning, and per-version runtime configuration in `canary.rc`. The project is a working server rather than a tutorial, with the real complexity in the C++ core and the Lua scripts that customise it.

The Docker quickstart starts four services at once

The most useful thing in the documentation is the local stack, which exists so you can run a test server without compiling Canary locally. It starts MariaDB for the database, the published Canary runtime image, MyAAC as the website and admin AAC, and the opentibiabr login-server as the client login webservice. The whole thing comes up from the `docker` directory with two commands:

cp .env.dist .env
docker compose up -d --build

There are also guarded start scripts that start the stack and clean safe Docker leftovers without removing database volumes, one for PowerShell and one for a POSIX shell:

.\up.ps1

sh ./up.sh

The warning attached to this quickstart is emphatic and worth repeating. It is for local development, testing and LAN demos, and it should not be exposed directly to the public Internet with the default test accounts and passwords. That is a sensible default for a quickstart, and it also tells you that the credentials and the network exposure are your responsibility, not the image's.

Three ports, and a login page that is deliberately absent

The default local endpoints are listed plainly: the website and admin interface on `http://localhost:8080`, the client login webservice on `http://localhost:8088/login`, and the game port on `7172`. The third detail is the interesting one, because MyAAC's `login.php` is intentionally removed from the quickstart image, and clients should use the login-server only. That is a security decision baked into the image, and it is the kind of detail that usually only shows up in documentation written by someone who has been burned. The longer form setup lives in `docker/DOCKER.md`, which covers the environment variables, the test account and troubleshooting, and a beginner guide is kept separately at `docs/docker/quickstart-for-beginners.md`. If you are evaluating the project, these two documents are where the operational reality lives, not the README.

Tests run through mise with pinned tool versions

The test workflow is defined as mise tasks rather than as ad hoc commands, and the tool versions are pinned in `.mise.toml` so that a build on your machine matches a build on CI. From the repository root the sequence is:

mise install
mise run configure linux-debug
mise run build linux-debug
mise run test linux-debug

The configuration name is the axis of variation, and the documentation notes that linux-debug can be replaced with macos-debug or windows-debug as needed. The detailed guidance on adding tests and on the frameworks used lives in `tests/README.md`, and the repository has a `tests/` directory to match. The repository also carries quality tooling that shows up in the file listing, a `.clang-format` and a `.cmake-format` for formatting, a `.cmake-lint` and a `.yamllint.yaml` for linting, a `.reviewdog.yml` for review automation, and a `.sonarcloud.properties` for the quality gate that the badge at the top of the README points at. The point of the mise setup is reproducibility: a new contributor should get the same toolchain as everyone else without reading a wiki page.

The Lua API reference is generated from the C++ bindings

One of the more thoughtful pieces of the project is how its Lua documentation is produced. The Lua API reference and the VSCode IntelliSense stubs are generated from the C++ Lua bindings during startup, and only when the `generateLuaApiDocs` option is enabled. The repository's `.luarc.json` already adds the `docs/lua-api` directory to the Lua Language Server workspace library, so a developer using the language server gets completion for the engine's Lua API without any extra setup. For VSCode workspace settings there is a separate helper, `tools/setup_vscode_lua_api.ps1`. The alternative to all of this is a hand-written API document that goes stale the moment a binding changes, so the generated approach is what makes the scripting surface usable in an editor at all. It also means the reference always describes the exact build you are running.

Protocol support spans three client generations

The documentation for multiprotocol runtime profiles covers the current runtime, the 11.00 contract and the 8.60 contract, together with the port layout, client preparation and a validation checklist. That is the kind of compatibility surface that decides whether an emulator is useful to you or not, because an OpenTibia server has to speak the same wire protocol as the client that connects to it. The recommended tooling is listed alongside it. The Assets Editor is described as the single asset source of truth, from which legacy-compatible `.dat` and `.spr` packages can be exported for 8.60 clients out of the same current asset set. Remere's Map Editor handles the world, OTClient Redemption is the client, the Tibia Extended Client Library prepares compatible 8.60 and 11.00 CipSoft clients with extended limits, config-driven login redirect and per-client local state, and a game client is linked for download. A separate document covers hardware sizing and capacity planning, with RAM and CPU measurement and a comparison of training and hunting workloads, which is the document to read before you decide how many players a box can hold.

GPL-2.0, a July release, and pushes into October

The licence is GPL-2.0, which matters more here than in most projects, because a server emulator is the kind of software people run as a service and sometimes want to modify privately. The release history shows v3.5.0 on 2026-05-21, v3.6.0 on 2026-06-09 and v3.6.1 on 2026-07-01, and the last push to the repository was on 2026-10-17 with the repository not archived. Nightly builds are published as GitHub Actions artifacts, and the documentation is clear about what they are for, useful for testing recent changes from the main branch but possibly containing behaviour that is not in a stable release yet. Support runs through the OpenTibiaBR Discord, and the documentation makes a distinction worth repeating: the issue tracker is for bugs, improvements and technical project tasks, and it is not a support forum. The project also accepts contributions in several forms, including validating releases, nightly builds and recent changes, which is unusual and useful for a project whose correctness depends on protocol compatibility.

Editorial conclusion

Server operators and developers who want to run an OpenTibia-compatible server for local testing, LAN demos or protocol work will get a maintained fork with a reproducible container stack, pinned build tasks and generated Lua API documentation. It is the wrong choice if you need a turnkey public server, since the documentation explicitly warns against exposing the quickstart with its default test accounts. Before adopting it, read the Docker quickstart notes for the account and environment setup, check the multiprotocol runtime profile document against the client version you intend to support, and run `mise run test linux-debug` to see whether the build works on your own toolchain.

Frequently asked questions

Official sources

1. License: GPL-2.0
2. opentibiabr/canary on GitHub
3. Project website
4. README
5. Releases