batman

2024-09-25 22:12:09 -04:00
commit f34c2fb05a
4 changed files with 235 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,143 @@
+# 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:
+     ```bash
+     ./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:
+     ```bash
+     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:
+     ```bash
+     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:
+     ```bash
+     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:
+     ```yaml
+     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:
+     ```bash
+     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:
+     ```bash
+     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:
+
+```bash
+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](https://mariadb.com/kb/en/) and [Docker Compose](https://docs.docker.com/compose/).
+
+Happy developing! 🎉
+
+If you run into any problems, please don't hesitate to reach out!