Admincraft WebSocket

WebSocket server to control Minecraft Bedrock Dockerized servers with Admincraft.

What is Admincraft WebSocket?

Admincraft WebSocket allows remote control of Minecraft Bedrock servers hosted in Docker. It uses WebSocket technology to provide secure, real-time communication with the Minecraft server, executing commands and monitoring server activity from anywhere.

Current Project Status

• Designed to work alongside Admincraft for GUI-based server management.
• Currently optimized for use with Oracle Always Free, using a server created with docker-minecraft-bedrock-server.

Issues

To open an issue, please use the Admincraft's issues page.

Getting Started

Prerequisites

To run Admincraft WebSocket, ensure you have the Docker installed.

Installation

You can set up your server following the server setup guide from Admincraft, in summary you need to:

1. Set up your environment:

   Get the docker-compose.yml file and edit it with your secret key:

   SECRET_KEY=your_secret_key_here

   Define minecraft container name for websocket, if it is not "minecraft": MC_NAME=YOUR_MINECRAFT_CONTAINER_NAME

2. Build and run the Docker container:

   sudo docker-compose up --build

   The WebSocket server will be available on port 8080.

Development

Running Locally

1. Run a demo container

   sudo docker run -p 8080:8080 --name admincraft-websocket -e SECRET_KEY=your_secret_key_here admincraft-websocket

2. The server will start on port 8080 by default.

Running together with docker compose

Change the websocket service in the docker-compose.yml file to remove the image configuration and add the build configuration to point to the local folder with the project code:

version: "3"
services:

  [...]

  websocket:
    container_name: websocket
    build:
      context: ./admincraft-websocket
      dockerfile: Dockerfileadmincraft-websocket:latest
    restart: always
    depends_on:
      # Make sure the minecraft service starts before the websockets service
      minecraft:
        condition: service_healthy
    ports:
      - 8080:8080
    volumes:
      # Mount Docker socket
      - /var/run/docker.sock:/var/run/docker.sock
      # Needed if environment.USE_SSL is "true"
      - ./certs:/usr/src/app/certs:ro
    environment:
      # Login password to use in admincraft (use alphanumeric characters only)
      SECRET_KEY: YOUR_SECRET_KEY_HERE
      # Enable or disable SSL
      USE_SSL: "false"

You can also run a separate docker compose file by providing it: sudo docker compose -f docker-compose_ssl.yml up -d

Troubleshoot

You can stop the servers, remove all containers and all images with:

sudo docker compose down
sudo docker rm -vf $(sudo docker ps -aq)
sudo docker rmi -f $(sudo docker images -aq)

Multi-architecture Docker Build & Push

Automated Builds with GitHub Actions

This repository includes a GitHub Actions workflow that automatically builds and pushes multi-architecture Docker images to Docker Hub when changes are pushed to the main branch.

To set this up:

1. Add Docker Hub secrets to your GitHub repository:

   • Go to your repository's Settings > Secrets and variables > Actions
   • Add these secrets:
     • DOCKERHUB_USERNAME: Your Docker Hub username
     • DOCKERHUB_TOKEN: A Docker Hub access token (create one at Docker Hub Account Settings)

2. Push changes to the main branch or manually trigger the workflow:

   • The workflow will automatically run when you push to the main branch
   • You can also manually trigger it from the Actions tab in your repository

Manual Build Process

If you prefer to build and push the Docker image manually:

1. Install Docker Buildx (if not already installed):

   Ensure Docker Buildx is available:

   sudo docker buildx create --use

2. Create or use a multi-architecture builder:

   Create a new builder instance:

   sudo docker buildx create --name admincraft-websocket-builder --use --driver docker-container

   To use an existing instance:

   sudo docker buildx use admincraft-websocket-builder

3. Build the Docker images for both architectures:

   Use the following command to build and push images for both amd64 and arm64:

   sudo docker buildx build --platform linux/amd64,linux/arm64 -t your-docker-username/admincraft-websocket:latest --push .

4. Verify the images on Docker Hub:

   After the build is complete, check your Docker Hub repository to ensure both architectures are available.

Architecture

The Admincraft WebSocket Server operates alongside a Minecraft Bedrock server hosted in Docker. All arechitecture details can be found here.

License

Licensed under the GPLv3 License.