Tuning and Diagnostics

This page is intended for quick checks of common operational issues.

1. Check backend and MariaDB service logs

From your deployment directory (where docker-compose.yml is located), the following command can be run:

docker compose ps

It should be verified that backend and mariadb containers are running.

docker compose logs --tail=200 backend
docker compose logs --tail=200 mariadb

Useful patterns that can be checked:

Backend: database connection errors, migration failures, startup exceptions.
MariaDB: access denied errors, initialization failures, corrupted tables, out-of-disk warnings.

2. System requirements

Based on deployment experience, 1 vCPU, 512 MB RAM, and 10 GB disk are not enough for stable operation on Ubuntu. With this configuration, MariaDB did not work reliably, and both memory and disk were fully utilized.

Recommended minimum requirements:

1 vCPU
1 GB RAM
20 GB disk
Swap configured

If RAM cannot be increased to more than 2 GB, swap should be configured: How To Add Swap Space on Ubuntu 22.04

3. MariaDB tuning

MariaDB is the most memory-intensive service in this stack. In this section, practical tuning for low-resource servers is described.

3.1 MariaDB service tuning

A custom my.cnf can be used to tune MariaDB memory usage.

touch mariadb_config.cnf

The following content can be used in mariadb_config.cnf:

[mysqld]
innodb_buffer_pool_size = 256M

max_connections = 20
thread_cache_size = 8

tmp_table_size = 16M
max_heap_table_size = 16M
sort_buffer_size = 512K
read_buffer_size = 256K

performance_schema = OFF

Explanation:

innodb_buffer_pool_size is the main memory consumer; 256M is a balanced value for a 1 GB RAM server.
performance_schema is useful for debugging, but it adds overhead (often around 50-100 MB).
max_connections is limited because each connection uses memory buffers; 20 is usually enough for this setup.
The remaining parameters control temporary in-memory tables and per-session buffers.

3.2 Memory limitations for MariaDB service in docker compose

Memory limits can also be enforced in Docker Compose. This helps ensure that all host memory is not consumed by the mariadb container and application stability is maintained.

docker-compose.yml after MariaDB tuning:

services:
  mariadb:
    image: mariadb:11.4
    restart: always
    command: ['--wait_timeout=86400', '--interactive_timeout=86400']
    env_file:
      - bangi-db.env
    volumes:
      - .mariadb:/var/lib/mysql
      - ./mariadb_config.cnf:/etc/mysql/conf.d/my.cnf
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
  landing-renderer:
    image: php:8.2-apache
    volumes:
      - ./landings:/var/www/html/landings
  backend:
    image: ghcr.io/devalentino/bangi-backend:dev-f47bb3d
    restart: always
    env_file:
      - bangi-backend-config.env
      - bangi-db.env
    ports:
      - '8000:5000'
    volumes:
      - ./landings:/app/landings
      - ./IP2LOCATION-LITE-DB1.IPV6.BIN:/app/IP2LOCATION-LITE-DB1.IPV6.BIN
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://0.0.0.0:5000/api/v2/health" ]
      interval: 120s
      timeout: 10s
      retries: 3
      start_period: 120s
    depends_on:
      mariadb:
        condition: service_healthy
  ui:
    image: ghcr.io/devalentino/bangi-ui:dev-4a70be3
    restart: always
    ports:
      - '8001:80'
    volumes:
      - ./bangi-ui-config.js:/usr/share/nginx/html/app-config.js

Explanation:

./mariadb_config.cnf:/etc/mysql/conf.d/my.cnf mounts the tuned MariaDB config into the container.
deploy.resources defines memory limits and reservations for the mariadb service.
If you run plain Docker Compose (non-Swarm), verify that your Compose version applies these limits in your environment.

3.3 Applying changes

The following command can be run to apply configuration changes:

docker compose down && docker compose up -d