Docker

Docker

So using Docker can save you some installation hassle, but you'll need to have it 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/

Note : if you're NOT a PHP/SQL expert this will save you time but beware that understanding Docker also requires some practice of its own ...

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/php8
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/php8  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 & 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

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 & 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 current host, also check its facial port responds.

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).

! ATTENTION ! in all 3 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, eg here 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)

Bot config

The same way we've prepared our DB, we need to make our future Bebot able to connect to the game and the DB.

Also, beware Docker works in a way that makes the bot wipe 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 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 & possibly AO guild (true+number, otherwise false+00000001).

In Mysql.conf => set you bot database, user, pass & server (possibly :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 33306:3306 -d mariadb --restart=always

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

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" & "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 ^_^

Control

Now to control 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

To see realtime life of the Bebot : docker logs -f <full-containername> (Ctrl+c to exit)

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

To stop a given container : docker stop <full-containername>

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

And if Bebot git code was patched, you simply have to restart the container (stop then rerun) and it will auto-update.

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

Conclusion

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