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

Generally consider Docker is quite nice if you run 1 (or few) bot(s), or want a very quick discovery on Bebot's functions.

Beyond this, if you wanted to run multiple bots, loot at the classical way explained in both README and http://wiki.bebot.link/index.php/Installation

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

(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 & 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 (edit SQL config file, etc).

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 & 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 remember it)

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

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 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 (can use -a parameter to see all)

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 delete a buggy container : docker rm -f <full-containername> (not undoable so beware !)

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

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

Conclusion

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