Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve setup instructions #48

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Improve setup instructions #48

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 16 additions & 7 deletions setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Setup
---
# MYSQL setup

We recommend using a Docker container to run your first MySQL server. This is the easiest way to get started.
We recommend using a Docker container to run your first MySQL server. This is the easiest way to get started and it works on all major operating systems (Linux, macOS, and Windows).

## Option 1: Use a Docker container

Expand All @@ -13,6 +13,14 @@ Please make sure you have docker installed and configured. You can follow the in
docker run hello-world
```

> ## Permission issues on Linux
> If you installed Docker Engine on Linux (instead of Docker Desktop), you will encounter an error while trying to run the above command that will look something like this.
> ```
> docker: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Post "http://%2Fvar%2Frun%2Fdocker.sock/v1.24/containers/create": dial unix /var/run/docker.sock: connect: permission denied.
> ```
> To solve it you will need to run the commands with ``sudo`` or follow [these instructions](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
{: .callout}

Once Docker is installed and configured, we will run a mySQL server using the
[official Docker image](https://hub.docker.com/_/mysql). We require to two ingredients to setup the MySQL server:
* A port number to communicate with the server. MySQL server uses port ``3306`` by default.
Expand Down Expand Up @@ -56,8 +64,8 @@ apptainer --version
```

We will use the same image as in Option 1.
Appteiner images are readonly if overlayfs is not available, so we'll be mounting the socket and database directories. This allows also for some persistency.
Depending on the system settings unprivileged Apptainer may not be allowed to bind to ports, so we'll use a socket file to connect to the server.
Apptainer images are readonly if overlayfs is not available, so we'll be mounting the socket and database directories. This allows also for some persistency.
Depending on the system settings, unprivileged Apptainer may not be allowed to bind to ports, so we'll use a socket file to connect to the server.
First move to a local directory: the image is not small and disk access will be faster, e.g. `mkdir /scratch/<username>/mysql-apptainer; cd /scratch/<username>/mysql-apptainer`.
Then execute the following commands to run the MySQL server in an Apptainer instance (replace mypassword with your password):
```bash
Expand All @@ -66,24 +74,25 @@ mkdir -p ./mysql/var/lib/mysql/ ./mysql/run/mysqld
apptainer pull --name mysql.sif docker://mysql
apptainer instance start --bind ${PWD} --bind ${PWD}/mysql/var/lib/mysql/:/var/lib/mysql --bind ${PWD}/mysql/run/mysqld:/run/mysqld ./mysql.sif mysql
apptainer instance list # just to make sure the instance started
apptainer exec instance://mysql mysqld --initialize
apptainer exec instance://mysql mysqld --init-file=${PWD}/.mysqlrootpw &
```
If you don't run the last command in background the terminal will be used by the server console and you'll have to use another terminal for other commands.
The ``&`` at the end of the last command will make it run in the background. You can press enter after the logs are printed, and you will see that you can continue using the terminal. If you don't run the last command in background the terminal will be used by the server console and you'll have to use another terminal for other commands.

To test that if everything is up and running, execute the following command:
```bash
apptainer exec instance://mysql mysql -S /var/run/mysqld/mysql.sock -u root -pmypassword
apptainer exec instance://mysql mysql -S /var/run/mysqld/mysqld.sock -u root -pmypassword
```
Remember to use it also throughout the tutorial instead of the docker command.

You may want to use a different password and a safer way to run mysql id to avoid to put the password in the command line, e.g. save in mysqlclient.ini the following:
You may want to use a different password and a safer way to run mysql id to avoid to put the password in the command line, e.g. save in ``mysqlclient.ini`` the following:
```
[client]
password="mypassword"
```
And then run with (--defaults-extra-file must be the first option):
```bash
apptainer exec instance://mysql mysql --defaults-extra-file=myconf -S /var/run/mysqld/mysql.sock -u root
apptainer exec instance://mysql mysql --defaults-extra-file=mysqlclient.ini -S /var/run/mysqld/mysqld.sock -u root
```

If you are interested on learning more about Apptainer, take a look at the
Expand Down