Docker

Preamble

So using Docker can save you some installation hassle, especially if you're NOT a PHP/SQL expert it will save you huge time ... but beware that understanding Docker also requires some practice of its own !

Generally, you could consider Docker is no less than amazing if you'd run only one (or very few) bot(s), same if you'd want a very quick discovery on Bebot's functions. In such case Docker's unbeatable on many aspects :

With very few actions from you, thanks to Docker's automations based on simple lightweight textfiles, you would configure then install and quickly run some sort of isolated "VMs" bringing your bot(s) and DataBase to life.

But beyond, as if you wanted to optimizely run multiple bots from an unique PHP-code installation with all pointing towards same Database or needing some proxy (eg Aocp), it'd possibly not be the best choice as each instance would then weight full Docker image(s)/container(s) in RAM/CPU.

For such more complicated cases we'd rather point you at the classical way explained with details within both Bebot README and http://wiki.bebot.link/index.php/Installation

Now you're aware of this all, and if you feel ready for it, let's proceed into Docker below.

Install

Before anything else, you'll need to have Docker installed properly - depending on system hosting your bot(s) :

Windows => https://docs.docker.com/desktop/install/windows-install/

Linux => https://docs.docker.com/desktop/install/linux-install/

Mac => https://docs.docker.com/desktop/install/mac-install/

Just make sure you're properly installed then continue to next section.

Build

Once the software is installed, you first have to build an image from 2 docker elements below.

Create a dedicated folder (let's name it "botfolder" for later reference) and go in it to create these 2 text files :

"Dockerfile" (with no extension)

FROM alpine:latest
ENTRYPOINT ["/sbin/tini", "-g", "--"]
CMD ["/BeBot/docker-entrypoint.sh"]
RUN apk --no-cache --repository http://dl-3.alpinelinux.org/alpine/edge/community/ add \
    git php82-cli php82-phar php82-curl php82-sockets php82-pdo php82-pdo_mysql \
    php82-mbstring php82-ctype php82-bcmath php82-json php82-posix php82-simplexml \
    php82-dom php82-pcntl php82-zip php82-opcache php82-fileinfo php82-mysqli sudo tini
RUN adduser -h /BeBot -s /bin/false -D -H bebot
RUN git clone https://github.com/bitnykk/BeBot.git
COPY docker-entrypoint.sh /BeBot
RUN chmod +x /BeBot/docker-entrypoint.sh
RUN chown -R bebot:bebot /BeBot
RUN chown -R bebot:bebot /BeBot/.git
RUN sudo ln -s /usr/bin/php82 /usr/bin/php
USER bebot
WORKDIR /BeBot

"docker-entrypoint.sh"

#!/bin/ash
# shellcheck shell=dash
errorMessage() {
        echo "$*"
        exit 1
}
EXITCODE=255
git pull
while [ "$EXITCODE" -eq 255 ]; do
        trap "" TERM
        # shellcheck disable=SC2086
        /usr/bin/php  StartBot.php "$@"
        EXITCODE=$?
        trap - TERM
done
exit $EXITCODE

NB : if you want more details on the PHP modules and config, go at https://www.php.net/docs.php

Then in command line into that "botfolder" you'd send the following command :

docker build -t bebot-imagename .

(you can change "imagename" for anything you like but then you'll replace it below accordingly)

If all goes fine you should see something like "Building X.Ys (10/10) FINISHED" + several blue lines starting with "=>".

NOTE : if you already have a SQL server you can use it and skip to "DB prep" below. Otherwise you must also build another container for DataBase.

The principle is therefore nearly the same. First obtain the base files by doing :

docker pull mariadb:latest

(you also can choose an X.Y version you'd want instead of "latest" like 10.4 for example, or any other)

That once done you may see your created image(s) by doing :

docker image ls

(Note that you can also delete some image but it's undoable, so beware : docker image rm <full-imagename>)

DB prep

Now we have to configure both our SQL (so it's opened to Bebot's requests) and Bebot (so it connects to game server and our SQL).

For the SQL there are 3 possibilites :

1: you have an external server ; make sure it's reachable (eg : ping its ip) from your host, and check if its facial port is opened.

2: you opted for a local service on host ; so you'd usually will go for default ip 127.0.0.1 on usual SQL port (3306).

3: you're about to run a container for that ; be sure to check what ip/port are set when you'll "RUN" it (section below).

Here some command or documentation to verify all elements :

- IP/Network on Linux/Mac (try from a console : ip a) and Windows (also in console : ipconfig)

- Ports/Services on Linux/Mac https://vitux.com/find-open-ports-on-debian and Windows https://www.geeksforgeeks.org/how-to-check-open-tcp-ip-ports-in-windows

! ATTENTION ! in all 3 upper cases you will have to :

- CREATE a DATABASE dedicated for the bot (you can name it as you like but remember it)

- make an USER with PASSWORD and expected source (eg : @'%' to accept external requests)

- also GRANT that USER all PRIVILEGES on the DATABASE you created upper

If needed, you may have to read some SQL doc, as https://dev.mysql.com/doc/ and adapt it to you context.

But for generic example it will usually look like the following :

mysql (enters prompt, optional parameters are --user --password + for distant server --host)

> CREATE DATABASE bebotdb;

> CREATE USER 'bebotuzr'@'%' IDENTIFIED BY 'mypass';

> GRANT ALL PRIVILEGES ON bebotdb.* TO 'bebotuzr'@'%';

If you ain't sure, you can verify you work is fine by doing :

> SHOW DATABASES; (should show the DB you created upper among list)

> SELECT User, Host FROM mysql.user; (should show your upper user among list)

> SHOW GRANTS FOR 'bebotuzr'@'%'; (should show the upper GRANT among list)

Also find SQL config (usually .cnf) file(s) and check parameter "bind-address" is concordant.

Bot config

The same way we've prepared our DB for Bebot, we also need to make our Bebot able to connect to the game + to the DB.

Also, beware Docker works in a way that makes the bot wipes all its files at every new run (!) so we need to render some persistents.

For that reason we will extract some files within the image we built earlier, and save them at host level to protect them.

To do this, we will run this long line on Linux from our "botfolder" :

docker run --rm --entrypoint tar bebot-buildtest czf - Conf Custom Extras/Bank Extras/Scripts log Text > out.tar.gz && tar xzf out.tar.gz -C . && rm out.tar.gz && chmod 777 * -R && mv Conf/Bot.conf.dist Conf/Bot.conf && mv Conf/Mysql.conf.dist Conf/Mysql.conf

On Windows a part of it won't work at all, so we will only obtain compress datas into our "botfolder" :

docker run --rm --entrypoint tar bebot-buildtest czf - Conf Custom Extras/Bank Extras/Scripts log Text > out.tar.gz

(then we can use any Windows utility, as Winzip or 7-zip etc, to decompress these datas right in place)

In any case we end up with several new folders ("Conf", "Custom", "Extras", "log" and "Text") in our "botfolder".

Windows only : set permissive rights on all those folders/files (select all, right-click > Properties > Security) so our container can acces them.

We now must enter "Conf" folder to edit 2 files for runnability ; leave all quotes/double-quotes as they are, write your values inside of them.

Windows only : we also need to rename 2 files as Bot.conf and Mysql.conf (remove .dist in names).

In Bot.conf => set your bot account name, pass, char, server, guild if AoC, owner and possibly AO guild (true+number, otherwise false+00000001).

In Mysql.conf => set you bot database, user, pass and server (possibly server:port) ; all depends on your SQL situation as seen earlier ...

Run

We're now ready to run our container(s) : 1 only if we want Bebot with our usual SQL server, otherwise 2 for Bebot + SQL both as Docker containers.

For SQL (optional) :

docker run --name mariadb-containername -e MYSQL_ROOT_PASSWORD=mypass -p 3306:3306 -d mariadb-imagename --restart=always

(you can change "containername" for anything you like but remember it ; "imagename" must be an existing one created upper)

For Bebot (mandatory) :

Windows :

docker run -d --rm --name bebot-containername --memory=128M -v C:\Folder\botfolder\Conf:/BeBot/Conf -v C:\Folder\botfolder\Custom:/BeBot/Custom -v C:\Folder\botfolder\Extras\Bank:/BeBot/Extras/Bank -v C:\Folder\botfolder\Extras\Scripts:/BeBot/Extras/Scripts -v C:\Folder\botfolder\log:/BeBot/log -v C:\Folder\botfolder\Text:/BeBot/Text bebot-imagename

(replace "imagename" and "C:\Folder\botfolder" depending on your config ; "containername" is free to choose ; all host pathes before ":" use antislashes \)

Mac/Linux :

docker run -d --rm --name bebot-containername --memory=50M -v /path/to/botfolder/Conf:/BeBot/Conf -v /path/to/botfolder/Custom:/BeBot/Custom -v /path/to/botfolder/Extras/Bank:/BeBot/Extras/Bank -v /path/to/botfolder/Extras/Scripts:/BeBot/Extras/Scripts -v /path/to/botfolder/log:/BeBot/log -v /path/to/botfolder/Text:/BeBot/Text bebot-imagename

(same than up but all path use slashes / ; also if you have SQL as host local service add this setting before bebot-imagename : --network="host")

Your bot should now load and go online to respond commands - if you did it all well ^_^

Otherwise you can use this shape of command to troubleshoot better :

docker run --name bebot-containername (+ all parameters you need as -v and possibly --network etc ...) bebot-imagename

So you'll see what bot does realtime in your console. Then do Ctlr+c to exit (but that will shutdown the bot container).

Control

Now to check if your container(s) run properly, and to control things, you have a set of commands.

To show a list of running container(s) : docker ps (can use -a parameter to also see stopped ones)

To see realtime log of the Bebot : docker logs -f <full-containername> (Ctrl+c to exit which will NOT shutdown bot/container)

To enter a given container interactively : docker exec -it <full-containername> sh (Ctrl+p Ctrl+q to exit without shutting down neither)

To stop a given container : docker stop <full-containername> (bot should go offline as expected)

To start again a previously stopped container : docker start <full-containername> (otherwise daemon may throw run error of "already in use")

To delete a buggy container : docker rm -f <full-containername> (means full data loss, not undoable, so beware !)

If Bebot git code was patched, you simply restart container and it should auto-update : docker restart <full-containername>

Alternative manual way : enter the container, do "git pull" then exit and !restart the bot from ingame, which should provide same result.

You may setup some task(s) (crontab on Linux/Mac / Task Manager > Startup on Windows) to run some container(s) right at host startup.

Sources : https://manpages.debian.org/bullseye/cron/crontab.5.en.html / https://www.howtogeek.com/208224/how-to-add-a-program-to-startup-in-windows/

Same way you should strongly save your SQL datas frequently as Docker won't do it for you ; can use task(s) based on mysqldump for that.

Source : https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html

Conclusion

This guide is a work in progress, kept as simple as possible, and will evolve as we find improvements or tricks.

For more details and options you can refer to Docker official documentation here https://docs.docker.com/