mariadb-setup-guide/README.md

MariaDB Setup Guide

Welcome to the MariaDB Setup Guide! This documentation will guide you through the process of setting up your environment to use the MariaDB service with Docker Compose.

We provide a script to help you automate several of the configuration steps, but you can also perform these steps manually if needed.

Prerequisites

Before you begin, ensure you have the following installed:

• Docker
• Docker Compose

If you're setting up MariaDB using Docker for the first time, this guide will help you ensure everything is ready to get your services up and running.

---

Automatic Setup (Recommended)

We’ve provided a handy script setup.sh that will guide you through the setup interactively.

Steps to Run the Automatic Setup:

1. Run the Setup Script:

   • In your terminal, execute the following command:

     ./setup.sh
     

   • The script will prompt you for the following information:
     • MariaDB Database Name: The name of the database that will be created.
     • MariaDB Username: The user that will have access to this database.
     • MariaDB User Password: The password for the specified user.
     • MariaDB Root Password: The root password for the MariaDB instance.
     • MariaDB Port: The port to expose MariaDB on your host machine (default is 3307).

2. Confirm Updates to Configuration:

   • After collecting input, setup.sh will:
     • Update the .env file with your supplied values.
     • Modify compose.yaml, replacing the standard "db1" service name with the database name you provided.
     • Ensure the port settings are correctly updated in the compose.yaml.

3. Launch the Docker Containers:

   • Once the script finishes, bring up the Docker services with:

     docker compose up -d
     

   • This will launch the MariaDB container along with any other services in the background.

4. Verify the Setup:

   • Check the running containers and verify everything is up and running:

     docker ps
     

---

Manual Setup (If You're Not Using the Script)

Alternatively, you can perform the setup manually by following these steps:

1. Edit the .env File:

   • Open the .env file in your favorite text editor and update the following values:

     MARIADB_DATABASE="your_database_name"
     MARIADB_USER="your_user_name"
     MARIADB_PASSWORD="your_password"
     MARIADB_ROOT_PASSWORD="your_root_password"
     

   • Make sure these details match your desired configuration for the MariaDB database.

2. (Optional) Remove the Configuration Volume:

   • If you do not need to persist custom MariaDB configurations in the container, you can delete the db1-conf volume reference in the compose.yaml file.

3. Rename the "db1" in compose.yaml:

   • Find any occurrence of db1 in compose.yaml and replace it with a name of your choice:
     • This includes the service name under services and the volume name.
   • For example:

     services:
       your_db_service_name:
         image: mariadb
         container_name: your_db_service_name
         ...
     volumes:
       your_db_service_name-data:
         name: your_db_service_name-data
     networks:
       db:
         name: db
     

4. Bring Up the Docker Services:

   • After editing the files, run the following command to start the service:

     docker compose up -d
     

   • Docker Compose will create and spin up the MariaDB container in detached mode.

5. Verify the Setup:

   • You can verify the container is running by checking the list of running Docker containers:

     docker ps
     

---

Post-Setup

Once your containers are up and running, you should now have a functional MariaDB instance ready to use! You can use MySQL clients or other database management tools to connect to the database.

Connecting to MariaDB

To connect to your MariaDB database from the host machine, you can use the following details based on your .env configuration:

• Host: localhost
• Port: The port you specified during setup (e.g., 3307).
• Database Name: The name you gave (from the .env file).
• Username: The username you configured.
• Password: The password corresponding to the username.

You can use a CLI client like mysql to check the connection:

mysql -u your_user_name -p -h 127.0.0.1 -P 3307 your_database_name

---

Notes

• If you need to modify the configuration further, simply re-edit the .env or compose.yaml files.
• For advanced customizations or troubleshooting, refer to the official documentation for MariaDB and Docker Compose.

Happy developing! 🎉

If you run into any problems, please don't hesitate to reach out!