159 lines
5.1 KiB
Markdown
159 lines
5.1 KiB
Markdown
# 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:
|
||
|
||
0. **Clone the repository and make the script executable**
|
||
|
||
- Clone the Repository:
|
||
|
||
```bash
|
||
git clone https://git.jisoonet.com/el/mariadb-setup-guide.git && \
|
||
cd mariadb-setup-guide
|
||
```
|
||
|
||
- Make the script executable:
|
||
|
||
```bash
|
||
chmod +x setup.sh
|
||
```
|
||
|
||
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!
|