TON Docker image with MyTonCtrl

This is an official TON Docker image with MyTonCtrl administration utility inside.

During the very first start of the container, it downloads and installs MyTonCtrl automatically.

Prerequisites

To run, you need docker-ce, docker-buildx-plugin:

• Install Docker Engine on Ubuntu

Configuration

Build environment variables are configured in the .env file:

• TON_BRANCH - when building this image, you can specify which TON branch binaries will be based on. Actually it is a TAG name of TON Docker image, but it coincides with the branch name (default: latest, i.e. master branch)
• NETWORK - TON network passed to MyTonCtrl installer. Valid values are mainnet or testnet (default mainnet)
• GLOBAL_CONFIG_URL - URL of the TON blockchain configuration (default: Mainnet)
• MYTONCTRL_VERSION - MyTonCtrl build branch (default master)
• TELEMETRY - Enable/Disable telemetry (default true)
• IGNORE_MINIMAL_REQS - Ignore hardware requirements (default false)
• MODE - Install MyTonCtrl with specified mode (validator or liteserver, default validator)
• DUMP - Use pre-packaged dump. Reduces the duration of initial synchronization, but it takes time to download the dump. You can view the download status in the logs docker-compose logs -f. (default false)
• DUMP_VALIDATE_BEFORE_EXTRACT - Validate the downloaded lzip dump before extraction. This can take hours, so it is disabled by default. (default false)
• ARCHIVE_TTL - Archive time-to-live in seconds for the validator (default 86400)
• STATE_TTL - State time-to-live in seconds for the validator (default 86400)
• VERBOSITY - Verbosity level for the validator engine (default 1)
• CUSTOM_PARAMETERS - Additional parameters appended to the end of validator-engine ExecStart command in validator.service (default empty)
• PUBLIC_IP - Used when automatic detection of external IP does not work, e.g. in Kubernetes.
• VALIDATOR_PORT - Set custom validator UDP port (default 30001)
• QUIC_PORT - Set custom validator QUIC UDP port (default 31001)
• LITESERVER_PORT - Set custom lite-server TCP port (default 30003)
• VALIDATOR_CONSOLE_PORT - Set custom validator-console TCP port (default 30002)

Run TON node with MyTonCtrl v2

This is the simplest and the quickest way to set up and start the TON validator. It will use a historical dump of data to speed up the initial sync process. It will not start validation unless you top up the wallet. Below docker compose commands will create Docker volumes ton-work, mytoncore, mytonctrl, and ton-src. ton-work contains blockchain data, mytoncore contains MyTonCtrl settings and wallet data, mytonctrl contains files written under /usr/local/bin/mytonctrl, and ton-src contains the TON source checkout used by Fift/MyTonCtrl. Real paths of these volumes can be found using docker volume inspect <volume-name> command.

We recommend changing default Docker volumes' location, since the blockchain's data can grow rapidly, and TON validator requires fast disks.

Also, make sure you backed up your wallet data, that can be found in <mytoncore-volume-path>/wallets

Download the image and start the container

Download docker-compose.yml and .env files:

wget https://raw.githubusercontent.com/ton-blockchain/ton-docker-ctrl/refs/heads/main/.env
wget https://raw.githubusercontent.com/ton-blockchain/ton-docker-ctrl/refs/heads/main/docker-compose.yml

Adjust .env as per your needs and start the container. You have to set PUBLIC_IP otherwise the container will not start.

After setting PUBLIC_IP and other parameters, you are ready to start the MAINNET node.

To run TESTNET node, additionally change this in .env:

TON_BRANCH=testnet
NETWORK=testnet
GLOBAL_CONFIG_URL=https://ton.org/testnet-global.config.json

Now you are ready to start the container

docker compose up

or Docker only way:

docker volume create ton-work
docker volume create mytoncore
docker volume create mytonctrl
docker volume create ton-src

docker run -d --name ton-node \
        --env-file .env \
        -p "0.0.0.0:30001:30001/udp" \
        -p "0.0.0.0:31001:31001/udp" \
        -p "0.0.0.0:30003:30003/tcp" \
        -v ton-work:/var/ton-work \
        -v mytoncore:/usr/local/bin/mytoncore \
        -v mytonctrl:/usr/local/bin/mytonctrl \
        -v ton-src:/usr/src/ton \
        --restart unless-stopped \
        -it ghcr.io/ton-blockchain/ton-docker-ctrl:testnet

Use MyTonCtrl

Go inside the container and execute mytonctrl:

docker exec -ti ton-node bash
mytonctrl

Troubleshooting

Check the container logs:

docker logs ton-node
docker logs -f ton-node # in real-time

Run TON Archive node with MyTonCtrl v2

Download docker-compose-archive.yml and .env files:

wget https://raw.githubusercontent.com/ton-blockchain/ton-docker-ctrl/refs/heads/main/.env
wget -O docker-compose.yml https://raw.githubusercontent.com/ton-blockchain/ton-docker-ctrl/refs/heads/main/docker-compose-archive.yml

Edit volume creation parameters so they will point to your external storage:

volumes:
  ton:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/ton_data
  mytoncore:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/mytoncore_data 
  mytonctrl:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/mytonctrl_data
  ton-src:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: /path/to/ton_src

Remember to set PUBLIC_IP in .env. Start the archive node:

docker compose up

Build MyTonCtrl Docker image from sources

git clone https://github.com/ton-blockchain/ton-docker-ctrl.git && cd ./ton-docker-ctrl
docker compose -f docker-compose.build.yml build

Start the container

At least set PUBLIC_IP variable in .env file otherwise the container will not start.

docker compose -f docker-compose.build.yml up -d

Upgrade TON node:

There are three ways how to upgrade your TON node

docker compose way

docker compose pull
docker compose up -d

Docker only way

docker pull ghcr.io/ton-blockchain/ton-docker-ctrl:latest

And from the running container itself

docker exec -ti ton-node bash
mytonctrl
update master
upgrade master

Migrate a non-Docker TON node to a containerized MyTonCtrl v2

Specify paths to TON binaries and sources, as well as to TON work directory, but most importantly to MyTonCtrl settings and wallets.

docker run -d --name ton-node --network host --restart unless-stopped \
-v /mnt/data/ton-work:/var/ton-work \
-v /usr/bin/ton:/usr/bin/ton \
-v /usr/src/ton:/usr/src/ton \
-v /home/<USER>/.local/share:/usr/local/bin \
ghcr.io/ton-blockchain/ton-docker-ctrl:latest

Read the logs

docker logs ton-node
docker logs -f ton-node # in real-time

Get inside the container and run MyTonCtrl

docker exec -ti ton-node bash

Start the container skipping the original entrypoint execution

docker run -it --entrypoint=bash ghcr.io/ton-blockchain/ton-docker-ctrl:latest

Volume inspection

docker volume ls
docker volume inspect ton-work
docker volume inspect mytoncore
docker volume inspect mytonctrl
docker volume inspect ton-src

Uninstall the TON node

The TON dblockchain data will be deleted, as well as MyTonCtrl settings and wallets.

docker stop ton-node
docker rm ton-node
docker volume rm mytonctrl mytoncore ton-src ton-work