ACE Hosting Docker

This guide assumes that you're familiar with Docker its concepts and its usage.

For your convenience, we have in our repo a simple docker-compose.yml to make use of our docker container build.

Using the docker-compose.yml along with the below instructions are not sufficient on its own. Environment variables config file and DAT files must also be setup before starting the container. Even for non-Raspberry PI hosts, these additional details necessary for any instance running in docker can be found in the Raspberry Pi instructions for an example of standing up a dockerized version of ACEmulator.

Server Setup

Download the following files. For Github hosted code files, you can use the first link in a browser to access the interactive code browser and then click the Download button. If using a command line such as wget, use the raw.githubusercontent.com link to directly retrieve the file.

• docker-compose.yml
  • This file references two pre-built images, mysql:8.0 and acemulator/ace:latest
  • File download: https://github.com/ACEmulator/ACE/blob/master/docker-compose.yml
  • Raw file: https://raw.githubusercontent.com/ACEmulator/ACE/refs/heads/master/docker-compose.yml
• docker.env
  • Contains variables used when the containers start. It is recommended that you edit this file and change the two default mysql passwords even if only running a private server locally.
  • File download: https://github.com/ACEmulator/ACE/blob/master/docker.env
  • Raw file: https://raw.githubusercontent.com/ACEmulator/ACE/refs/heads/master/docker.env
• /Dats files
  • Download the ac-updates.zip containing dat files from https://mega.nz/#!Q98n0BiR!p5IugPS8ZkQ7uX2A_LdN3Un2_wMX4gZBHowgs1Qomng
  • Extract the *.dat files to a Dats subfolder. This typically should be relative to the location of your docker-compose.yml, because it contains a volume: mapping relative to current directory: - ./Dats:/ace/Dats

Your resulting directory structure should look like this:

/docker-compose.yml
/docker.env
/Dats/client_cell_1.dat
/Dats/client_local_English.dat
/Dats/client_portal.dat

Start ACE

Use a tool of your choice to run compose up on docker-compose.yml:

docker compose up -d

Monitor container output terminal, particularly for ace-server. It can take a couple minutes to initialize everything for the first time. The ace-server container will wait for mysql to fully start before it attempts to run. Thus, it may appear only ace-db container is started while mysql is still initializing internally, before ace-server even tries to start.

If *.dat files aren't located/accessible, then an error in the output will indicate this. As of writing, you will see the following output whenever the server is fully started successfully and ready:

ACEmulator command prompt ready.

Type "acecommands" for help.

ACE >> 2025-01-11 14:32:15,467 INFO : Registering ModManager commands...
2025-01-11 14:32:15,468 INFO : No mods to display.

Note: A number of additional directories will be created automatically by docker-compose.yml's volumes: mapping in the same directory where docker-compose.yml resides. These are mapped to a folder internal to the ace-server, which provides an easy mechanism to copy content from the docker host into the container, and additionally ensures this content is preserved if the container is deleted.

To access the ACE console

docker container attach --sig-proxy=false ace-server

To access the docker compose logs

docker compose logs -f

Restart ACE

docker compose restart

Stop ACE

From an attached ace-server prompt (see To access the ACE console), run the ACE console command:

/shutdown

This ensures all DB updates are flushed and the world is closed.

Then you can exist the ACE console and return to the docker host and stop the container normally:

docker compose down

Update ACE to latest released master

docker compose down
docker compose pull
docker compose up -d

Troubleshooting

Error failed to read dockerfile: open Dockerfile: no such file or directory

This can occur when starting the container in some tools, such as the VSCode Docker extension, which automatically generates a --build parameter for the Compose Up option. The docker-compose.yml includes the following:

  ace-server:
    build: .
    image: acemulator/ace:latest

Solution: Comment out build: . in the docker-compose.yaml. Rather then build from source, the image: reference is already sufficient to pull the pre-built image of the server:

  ace-server:
    # build: .
    image: acemulator/ace:latest

Explanation:

The build: . parameter assumes the file https://github.com/ACEmulator/ACE/blob/master/Dockerfile is present in the current directory. Typically for server hosting you would not have a Dockerfile file present, as you only copy docker-compose.yaml, docker.env, and Dat files. Typically only emulator developers building the ACE server from source code need the build: parameter with the Dockerfile. Therefore the solution is to comment outthis parameter and rely only on the prebuilt image: reference.