[Guide] Setting Up Gitea with MariaDB in Portainer on Synology


Summary

This guide walks through the process of setting up Gitea on a Synology NAS using Portainer, and configuring it to use an existing MariaDB container (bookstack-db). We ensure that Gitea can connect to the existing MariaDB and remove unnecessary configurations.


Table of Contents


1. Prerequisites

Before starting, ensure the following are set up:

  • Portainer running on Synology with Docker installed.
  • A MariaDB container (bookstack-db) already running in Portainer, which is used by both BookStack and Gitea.

Before we dive into the setup process, let’s review the folder structure in Synology File Station. This structure organizes the Docker services in a centralized directory for easy management.

Here’s a screenshot of the Docker folder structure on Synology File Station:

In this example, there are subfolders for BookStack, Gitea, Nextcloud, and Portainer. This helps in keeping all Docker-related data well-organized. The folder names should correspond to your Docker containers.


2. Setting Up Gitea Docker Compose

After organizing the folder structure, we will configure Docker Compose for Gitea in Portainer.

Here’s a screenshot of the Portainer Stacks in Synology:

In the Stacks section of Portainer, you can see the bookstack, tools, and web_services stacks. Each of these stacks will have its own Docker Compose configuration, and Gitea is part of the tools stack.

2.1 Docker Compose file for Mariadb (with Health Check)

Now, let’s focus on setting up Docker Compose for the MariaDB (bookstack-db), (please note that in my example I named the mariadb container bookstack-db because I initially installed this with bookstack) container with a health check to ensure that Gitea doesn’t start until MariaDB is ready.

Here is what needs to be added to MariaDB (bookstack-db) and the screenshot of what it looks like:

 healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

Here’s how this looks in Portainer:

The health check has been added, as shown in the screenshot. This ensures Gitea will only start after MariaDB (bookstack-db) is fully initialized and ready.

2.2 Configuring Environment Variables for Mariadb (bookstack-db)

In Portainer, you can also set up the environment variables for MariaDB. Here’s where the variables like MYSQL_ROOT_PASSWORD, MYSQL_DATABASE, MYSQL_USER, and MYSQL_PASSWORD are defined.

Here’s how the environment variables for MariaDB (bookstack-db) are configured in Portainer:

Make sure the values are correct and match the Compose file.

2.3 Docker Compose File for Gitea

Below is the updated Docker Compose file used to set up Gitea in a tools stack. This file configures Gitea to use the existing MariaDB container and uses the correct network.

version: '3.3'

networks:
  bookstack_network:
    name: bookstack_network  # Shared network with bookstack-db

services:
  server:
    image: gitea/gitea:1.22.3
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - DB_HOST=${DB_HOST}
      - DB_USER=${DB_USER}
      - DB_PASS=${DB_PASS}
      - DB_NAME=${DB_NAME}
    volumes:
      - /volume1/docker/gitea:/data
      - /etc/TZ:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    restart: unless-stopped
    networks:
      - bookstack_network
    entrypoint: >
      /bin/sh -c "
      until nc -z ${DB_HOST} 3306; do
        echo 'Waiting for ${DB_HOST}...';
        sleep 5;
      done;
      echo '${DB_HOST} is up!';
      exec /usr/bin/entrypoint"

Here’s how this Compose configuration looks in Portainer:

2.4 .env File for Gitea

To secure the database credentials, create a .env file to store sensitive information, and reference it in your docker-compose.yml.

# Database Configuration
DB_HOST=bookstack-db
DB_USER=gitea_user
DB_PASS=giteapassword
DB_NAME=gitea_db

Here is a screenshot of what it looks like.

3. Creating the Gitea Database in MariaDB

Once Gitea is set up and running, you’ll need to create a database and user in MariaDB (bookstack-db) for Gitea to use.

3.1 Access the bookstack-db Container

Run the following command to access the bookstack-db container and log into MariaDB:

docker exec -it bookstack-db /bin/bash
mysql -u root -p

When prompted, enter the root password for MariaDB.

3.2 Create the Gitea Database and User

Once logged into MariaDB, run the following SQL commands to create the Gitea database and user:

CREATE DATABASE gitea_db;
CREATE USER 'gitea_user'@'%' IDENTIFIED BY 'giteapassword';
GRANT ALL PRIVILEGES ON gitea_db.* TO 'gitea_user'@'%';
FLUSH PRIVILEGES;

3.3 Exit MariaDB

Once the database and user are created, exit MariaDB:

exit

4. Configuring Gitea with MariaDB

When you first access Gitea via http://<NAS_IP>:3000, you’ll be prompted to enter database information. Use the following settings:

  • Database Type: MySQL
  • Host: bookstack-db:3306
  • User: gitea_user
  • Password: giteapassword
  • Database Name: gitea_db

Click Test Connection to ensure Gitea can communicate with the database. If successful, complete the setup and proceed with the rest of the configuration.


5. Monitoring and Troubleshooting

5.1 Logs

To monitor the logs of Gitea or bookstack-db, use the following commands:

  • Gitea logs:
docker logs -f gitea

Here you can see how gitea waits for bookstack-db (mariadb) to startup and once it does we see it in the log. Then gitea will continue loading.

  • bookstack-db logs:
docker logs -f bookstack-db

This is how the log should look in bookstack-db (mariadb)

5.2 Resource Monitoring

Use Portainer or Synology’s Resource Monitor to track CPU, memory, and disk usage to ensure the system is not maxed out.

(Synology Resource Monitor can be found with a search and you can pin it to the taskbar)


6. Summary of Key Points

  • Gitea was set up in Portainer with a health check to ensure the MariaDB container (bookstack-db) is ready before Gitea connects.
  • Sensitive database credentials are stored in a .env file.
  • The bookstack_network was shared between Gitea and bookstack-db to ensure smooth communication.
  • A new database (gitea_db) and user (gitea_user) were created in MariaDB for Gitea.

Conclusion

By following this guide, you have successfully set up Gitea on your Synology NAS using Portainer with a MariaDB dependency. This setup ensures that Gitea only connects to MariaDB when the database is ready, providing a stable and reliable environment. Monitor logs and resource usage to maintain optimal performance.

1 Like

nice write up. if you can add screenshot, it will be more helpful.

1 Like

it looks amazing, keep up the good work.

1 Like