Docker

This container runs the auto-mcs headless interface through a browser-based terminal. It does not run the desktop GUI; for full remote management, pair a Telepath client.

Supported tags and architectures:

• Tags: latest, beta, any release version
• Architectures: amd64, arm64

Image source:

• Docker Hub: macarooniman/auto-mcs
• View the Dockerfile for this image

Running the Container

Basic Usage

To run auto-mcs with default settings:

env WEB_PORT=8080 WEB_USERNAME='root' WEB_PASSWORD='auto-mcs' \
sh -c 'docker run -d --name auto-mcs \
  -e WEB_PORT -e WEB_USERNAME -e WEB_PASSWORD \
  -p "$WEB_PORT:$WEB_PORT" -p 7001:7001 -p 25565:25565 \
  -v auto-mcs-data:/root/.auto-mcs \
  --add-host host.docker.internal:host-gateway \
  --restart unless-stopped \
  macarooniman/auto-mcs:latest'

This command:

• Runs auto-mcs in a container

• Exposes key ports:

  • 25565 for the default port of a Minecraft server
  • 8080 for the TTYD terminal (web interface)
  • 7001 for the Telepath API

  Note

  See transport security before exposing this publicly

• Stores data in a Docker volume named auto-mcs-data

• Secures the TTYD instance using the following credentials:

  • Username: root
  • Password: auto-mcs

• ⚠️ In order to use this image, you’ll have to change the default credentials. To do so, simply modify the WEB_USERNAME and WEB_PASSWORD parameters with the desired credentials.

  • Example: WEB_USERNAME='U$ern4me' WEB_PASSWORD='P@s$w0rd'

Note that the auto-mcs and ttyd binaries are precompiled for optimal compatibility. If you’d like to build these from source, please reference the guide below.

Using Docker Compose

To manage auto-mcs with Docker Compose, create a docker-compose.yml:

version: "3"
services:
  app:
    image: macarooniman/auto-mcs:latest
    container_name: auto-mcs
    stdin_open: true
    tty: true
    restart: unless-stopped

    environment:

      # Default web interface port
      WEB_PORT: "8080"

      # Change the web interface credentials
      WEB_USERNAME: "root"
      WEB_PASSWORD: "auto-mcs"

    ports:

      # Web interface (make this the same as WEB_PORT)
      - "8080:8080"

      # Telepath API (auto-mcs)
      - "7001:7001"

      # Add more ports based on the servers you create
      - "25565:25565"

    extra_hosts:
      - "host.docker.internal:host-gateway"

    volumes:
      - auto-mcs-data:/root/.auto-mcs

volumes:
  auto-mcs-data:

To run auto-mcs using Docker Compose, in the same directory run:

docker-compose up -d

Accessing the TTYD Web Interface

After running the container, open your browser and navigate to http://localhost:8080 for access to the TTYD web-based terminal. The default credentials are:

• Username: root

• Password: auto-mcs

• ⚠️ In order to use this image, you’ll have to change the default credentials. To do so, simply modify the WEB_USERNAME and WEB_PASSWORD parameters with the desired credentials.

  • Example: WEB_USERNAME: 'U$ern4me' WEB_PASSWORD: 'P@s$w0rd'

Data Persistence

The volume mount in the complete docker run example above (-v auto-mcs-data:/root/.auto-mcs) persists auto-mcs data across container restarts. In Docker Compose, the volume is defined as:

volumes:
  auto-mcs-data:

This volume will store the app data.

Volume permissions

auto-mcs needs read, write, and execute permissions for its data directory inside the container. If you’re using a bind mount to a directory on the host, ensure that the user running the container can access, modify, and execute everything inside of it.

If your mounted data directory requires full permissions, you can run the following on the Docker host:

chmod -R 777 /path/to/auto-mcs-data

Building the Image Locally

Prerequisites:

• Clone auto-mcs repo
• Clone auto-mcs-ttyd repo
• Alpine Linux 3.23

After cloning the repositories on Alpine, move to the root of the auto-mcs repository and run the following script to build auto-mcs:

# Install dependencies
apk add python3 py3-pip gcc pangomm-dev pkgconfig python3-dev zlib-dev libffi-dev musl-dev linux-headers mtdev-dev mtdev

# Build auto-mcs
cd build-tools
chmod +x build-docker.sh
./build-docker.sh

After building auto-mcs, move to the root of the auto-mcs-ttyd repository and run the following script to build auto-mcs-ttyd:

# Install dependencies
apk add build-base libwebsockets-evlib_uv bsd-compat-headers cmake json-c-dev libuv-dev libwebsockets-dev 'openssl-dev>3' samurai zlib-dev

# Build auto-mcs-ttyd
mkdir build && cd build
cmake ..
make && make install
mv -f ./ttyd ../../auto-mcs/docker

After building these binaries, move to auto-mcs/docker and build the Docker image locally with:

docker build -t yourusername/auto-mcs:latest .

If you need to build for different architectures, such as amd64 or arm64, you can use Docker Buildx:

docker buildx build --platform linux/amd64,linux/arm64 \
  -t yourusername/auto-mcs:latest --push .