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
- 2. Setting Up Gitea Docker Compose
- 3. Creating the Gitea Database in MariaDB
- 4. Configuring Gitea with MariaDB
- 5. Monitoring and Troubleshooting
- 6. Summary of Key Points
- Conclusion
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.