Merge pull request 'Updates and Fixes for Dockerfile and docker-compose, and docker installation guide' (#51) from phantomlan/artemis:develop into develop

Reviewed-on: Hay1tsme/artemis#51

Dockerfile

@@ -12,9 +12,9 @@ RUN chmod +x entrypoint.sh
 
 COPY index.py index.py
 COPY dbutils.py dbutils.py
+COPY read.py read.py
 ADD core core
 ADD titles titles
-ADD config config
 ADD log log
 ADD cert cert
 

docker-compose.yml

@@ -5,22 +5,23 @@ services:
     build: .
     volumes:
       - ./aime:/app/aime
+      - ./configs/config:/app/config
 
     environment:
       CFG_DEV: 1
       CFG_CORE_SERVER_HOSTNAME: 0.0.0.0
       CFG_CORE_DATABASE_HOST: ma.db
       CFG_CORE_MEMCACHED_HOSTNAME: ma.memcached
-      CFG_CORE_AIMEDB_KEY: keyhere
+      CFG_CORE_AIMEDB_KEY: <INSERT AIMEDB KEY HERE>
       CFG_CHUNI_SERVER_LOGLEVEL: debug
 
     ports:
-    - "80:80"
+      - "80:80"
-    - "8443:8443"
+      - "8443:8443"
-    - "22345:22345"
+      - "22345:22345"
 
-    - "8080:8080"
+      - "8080:8080"
-    - "8090:8090"
+      - "8090:8090"
 
     depends_on:
       db:
@@ -28,21 +29,29 @@ services:
 
   db:
     hostname: ma.db
-    image: mysql:8.0.31-debian
+    image: yobasystems/alpine-mariadb:10.11.5
     environment:
       MYSQL_DATABASE: aime
       MYSQL_USER: aime
       MYSQL_PASSWORD: aime
       MYSQL_ROOT_PASSWORD: AimeRootPassword
+      MYSQL_CHARSET: utf8mb4
+      MYSQL_COLLATION: utf8mb4_general_ci
+    ##Note: expose port 3306 to allow read.py importer into database, comment out when not needed
+    #ports:
+    #  - "3306:3306"
+    ##Note: uncomment to allow mysql to create a persistent database, leave commented if you want to rebuild database from scratch often
+    #volumes:
+    #  - ./AimeDB:/var/lib/mysql
     healthcheck:
-      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
+      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost", "-pAimeRootPassword"]
       timeout: 5s
       retries: 5
 
-
   memcached:
     hostname: ma.memcached
-    image: memcached:1.6.17-bullseye
+    image: memcached:1.6.22-alpine3.18
+    command: [ "memcached", "-m", "1024", "-I", "128m" ]
 
   phpmyadmin:
     hostname: ma.phpmyadmin
@@ -53,5 +62,5 @@ services:
       PMA_PASSWORD: AimeRootPassword
       APACHE_PORT: 8080
     ports:
-    - "8080:8080"
+    - "9090:8080"
 

docs/INSTALL_DOCKER.md

@@ -0,0 +1,246 @@
+# ARTEMiS - Docker Installation Guide
+
+This step-by-step guide will allow you to install a Contenerized Version of ARTEMiS inside Docker, some steps can be skipped assuming you already have pre-requisite components and modules installed.
+
+This guide assumes using Debian 12(bookworm-stable) as a Host Operating System for most of packages and modules.
+
+## Pre-Requisites:
+
+- Linux-Based Operating System (e.g. Debian, Ubuntu)
+- Docker (https://get.docker.com)
+- Python 3.9+
+- (optional) Git
+
+## Install Python3.9+ and Docker
+
+```
+(if this is a fresh install of the system)
+sudo apt update && sudo apt upgrade
+
+(installs python3 and pip)
+sudo apt install python3 python3-pip
+
+(installs docker)
+curl -fsSL https://get.docker.com -o get-docker.sh
+sh get-docker.sh
+
+(optionally install git)
+sudo apt install git
+```
+
+## Get ARTEMiS
+
+If you installed git, clone into your choice of ARTEMiS git repository, e.g.:
+```
+git clone <ARTEMiS Repo> <folder>
+```
+If not, download the source package, and unpack it to the folder of your choice.
+
+## Prepare development/home configuration
+
+To build our Docker setup, first we need to create some folders and copy some files around
+- Create 'aime', 'configs', 'AimeDB', and 'logs' folder in ARTEMiS root folder (where all source files exist)
+- Inside configs folder, create 'config' folder, and copy all .yaml files from example_config to config (thats all files without nginx_example.conf)
+- Edit .yaml files inside configs/config to suit your server needs
+- Edit core.yaml inside configs/config:
+```
+set server.listen_address: to "0.0.0.0"
+set title.hostname: to machine's IP address, e.g. "192.168.x.x", depending on your network, or actual hostname if your configuration is already set for dns resolve
+set database.host: to "ma.db"
+set database.memcached_host: to "ma.memcached"
+set aimedb.key: to "<actual AIMEDB key>"
+```
+
+## Running Docker Compose
+
+After configuring, go to ARTEMiS root folder, and execute:
+
+```
+docker compose up -d
+```
+
+("-d" argument means detached or daemon, meaning you will regain control of your terminal and Containers will run in background)
+
+This will start pulling and building required images from network, after it's done, a development server should be running, with server accessible under machine's IP, frontend with port 8090, and PHPMyAdmin under port 9090.
+
+- To turn off the server, from ARTEMiS root folder, execute:
+
+```
+docker compose down
+```
+
+- If you changed some files around, and don't see your changes applied, execute:
+
+```
+(turn off the server)
+docker compose down
+(rebuild)
+docker compose build
+(turn on)
+docker compose up -d
+```
+
+- If you need to see logs from containers running, execute:
+
+```
+docker compose logs
+```
+
+- add '-f' to the end if you want to follow logs.
+
+## Running commands
+
+If you need to execute python scripts supplied with the application, use `docker compose exec app python3 <script> <command>`, for example `docker compose exec app python3 dbutils.py version`
+
+## Persistent DB
+
+By default, in development mode, ARTEMiS database is stored temporarily, if you wish to keep your database saved between restarts, we need to bind the database inside the container to actual storage/folder inside our server, to do this we need to make a few changes:
+
+- First off, edit docker-compose.yml, and uncomment 2 lines:
+
+```
+(uncomment these two)
+#volumes:
+#  - ./AimeDB:/var/lib/mysql
+```
+
+- After that, start up the server, this time Database will be saved in AimeDB folder we created in our configuration steps.
+- If you wish to save it in another folder and/or storage device, change the "./AimeDB" target folder to folder/device of your choice
+
+NOTE (NEEDS FIX): at the moment running development mode with persistent DB will always run database creation script at the start of application, while it doesn't break database outright, it might create some issues, a temporary fix can be applied:
+
+- Start up containers with persistent DB already enabled, let application create database
+- After startup, `docker compose down` the instance
+- Edit entrypoint.sh and remove the `python3 dbutils.py create` line from Development mode statement
+- Execute `docker compose build` and `docker compose up -d` to rebuild the app and start the containers back
+
+## Adding importer data
+
+To add data using importer, we can do that a few ways:
+
+### Use importer locally on server
+
+For that we need actual GameData and Options supplied somehow to the server system, be it wsl2 mounting layer, a pendrive with data, network share, or a direct copy to the server storage
+With python3 installed on system, install requirements.txt directly to the system, or through python3 virtual-environment (python3-venv)
+Default mysql/mariadb client development packages will also be required
+
+- In the system:
+
+```
+sudo apt install default-libmysqlclient-dev build-essential pkg-config libmemcached-dev
+sudo apt install mysql-client
+OR
+sudo apt install libmariadb-dev
+```
+
+- In the root ARTEMiS folder
+
+```
+python3 -m pip install -r requirements.txt
+```
+
+- If we wish to layer that with python3 virtual-environment, install required system packages, then:
+
+```
+sudo apt install python3-venv
+python3 -m venv /path/to/venv
+cd /path/to/venv/bin
+python3 -m pip install -r /path/to/artemis/requirements.txt
+```
+
+- Depending on how you installed, now you can run read.py using:
+- For direct installation, from root ARTEMiS folder:
+
+```
+python3 read.py <args>
+```
+
+- Or from python3 virtual environment, from root ARTEMiS folder:
+
+```
+/path/to/python3-venv/bin/python3 /path/to/artemis/read.py <args>
+```
+
+- We need to expose database container port, so that read.py can communicate with the database, inside docker-compose.yml, uncomment 2 lines in the database container declaration (db):
+
+```
+#ports:
+#  - "3306:3306"
+```
+
+- Now, `docker compose down && docker compose build && docker compose up -d` to restart containers
+
+Now to insert the data, by default, docker doesn't expose container hostnames to root system, when trying to run read.py against a container, it will Error that hostname is not available, to fix that, we can add database hostname by hand to /etc/hosts:
+
+```
+sudo <editor of your choice> /etc/hosts
+add '127.0.0.1  ma.db' to the table
+save and close
+```
+
+- You can remove the line in /etc/hosts and de-expose the database port after successful import (this assumes you're using Persistent DB, as restarting the container without it will clear imported data).
+
+### Use importer on remote Linux system
+
+Follow the system and python portion of the guide, installing required packages and python3 modules, Download the ARTEMiS source.
+
+- Edit core.yaml and insert it into config catalog:
+
+```
+database:
+  host: "<hostname of target system>"
+```
+
+- Expose port 3306 from database docker container to system, and allow port 3306 through system firewall to expose port to the system from which you will be importing data. (Remember to close down the database ports after finishing!)
+
+- Import data using read.py
+
+### Use importer on remote Windows system
+
+Follow the [windows](docs/INSTALL_WINDOWS.md) guide for installing python dependencies, download the ARTEMiS source.
+
+- Edit core.yaml and insert it into config catalog:
+
+```
+database:
+  host: "<hostname of target system>"
+```
+
+- Expose port 3306 from database docker container to system, and allow port 3306 through system firewall to expose port to the system from which you will be importing data.
+- For Windows, also allow port 3306 outside the system so that read.py can communicate with remote database. (Remember to close down the database ports after finishing!)
+
+# Troubleshooting
+
+## Game does not connect to ARTEMiS Allnet Server
+Double check your core.yaml if all addresses are correct and ports are correctly set and/or opened.
+
+## Game does not connect to Title Server
+Title server hostname requires your actual system hostname, from which you set up the Containers, or it's IP address, you can get the IP by using command `ip a` which will list all interfaces, and one of them should be your system IP (typically under eth0).
+
+## Unhandled command in AimeDB
+Make sure you have a proper AimeDB Key added to configuration.
+
+## Memcached Error in ARTEMiS application causes errors in loading data
+Currently when running ARTEMiS from master branch, there is a small bug that causes app to always configure memcached service to 127.0.0.1, to fix that, locate cache.py file in core/data, and edit:
+
+```
+memcache = pylibmc.Client([hostname]), binary=True)
+```
+
+to:
+
+```
+memcache = pylibmc.Client(["ma.memcached"], binary=True)
+```
+
+And build the containers again.
+This will fix errors loading data from server.
+(This is fixed in development branch)
+
+## read.py "Can't connect to local server through socket '/run/mysqld/mysqld.sock'"
+
+sqlalchemy by default reads any ip based connection as socket, thus trying to connect locally, please use a hostname (such as ma.db as in guide, and do not localhost) to force it to use a network interface.
+
+### TODO:
+
+- Production environment

readme.md

@@ -40,7 +40,7 @@ Games listed below have been tested and confirmed working. Only game versions ol
 - mysql/mariadb server
 
 ## Setup guides
-Follow the platform-specific guides for [windows](docs/INSTALL_WINDOWS.md) and [ubuntu](docs/INSTALL_UBUNTU.md) to setup and run the server.
+Follow the platform-specific guides for [windows](docs/INSTALL_WINDOWS.md), [ubuntu](docs/INSTALL_UBUNTU.md) or [docker](docs/INSTALL_DOCKER.md) to setup and run the server.
 
 ## Game specific information
 Read [Games specific info](docs/game_specific_info.md) for all supported games, importer settings, configuration option and database upgrades.