diff --git a/docs/configuration-files/env-file.rst b/docs/configuration-files/env-file.rst index 1f90bbb9..a429c29e 100644 --- a/docs/configuration-files/env-file.rst +++ b/docs/configuration-files/env-file.rst @@ -311,6 +311,8 @@ your system, however it could also be a different value. the host system and a running Docker container. +.. _env_timezone: + TIMEZONE -------- @@ -733,6 +735,8 @@ always be ``/shared/httpd/``. ``docker-compose rm``. +.. _env_mysql_datadir: + HOST_PATH_MYSQL_DATADIR ----------------------- @@ -778,6 +782,8 @@ The directory structure will look something like this: ``docker-compose rm``. +.. _env_pgsql_datadir: + HOST_PATH_PGSQL_DATADIR ----------------------- @@ -817,6 +823,8 @@ The directory structure will look something like this: ``docker-compose rm``. +.. _env_mongo_datadir: + HOST_PATH_MONGO_DATADIR ----------------------- diff --git a/docs/getting-started/best-practice.rst b/docs/getting-started/best-practice.rst new file mode 100644 index 00000000..5ab97951 --- /dev/null +++ b/docs/getting-started/best-practice.rst @@ -0,0 +1,182 @@ +.. _getting_started_best_practice: + +************* +Best practice +************* + +If you have already read all documents in the Getting started guide, you should be ready to fully +operate the Devilbox. This section builds on top of that and gives you some best-practices as well +as tips and tricks. + + +**Table of Contents** + +.. contents:: :local: + + +Move data out of Devilbox directory +=================================== + +One thing you should take into serious consideration is to move data such as your projects as well +as persistent data of databases out of the Devilbox git directory. + +The Devilbox git directory should be something that can be safely deleted and re-created without +having to worry about loosing any project data. There could also be the case that you have a +dedicated hard-disk to store your projects or you have your own idea about a directory structure +where you want to store your projects. + + +Projects +-------- + +So let's assume all of your projects are already in place under ``/home/user/workspace/web/``. Now +you decide to use the Devilbox, but still want to keep your projects where they are at the moment. + +All you have to to is to adjust the path of :ref:`env_httpd_datadir` in the ``.env`` file. + +.. code-block:: bash + + # Navigate to Devilbox git directory + host> cd path/to/devilbox + + # Open the .env file with your favourite editor + host> vim .env + +Now Adjust the value of :ref:`env_httpd_datadir` + +.. code-block:: bash + :name: .env + :caption: .env + :emphasize-lines: 1 + + HOST_PATH_HTTPD_DATADIR=/home/user/workspace/web + +That's it, whenever you start up the Devilbox ``/home/user/workspace/web/`` will be mounted into +the PHP and the web server container into ``/shared/httpd/``. + + +Databases +--------- + +Moving your projects out of the Devilbox git directory is one step, you still need to take care +about persistent data of all available databases as well. + +Let's assume you desired location for database storage is at ``/home/user/workspace/db/``. + +MySQL +^^^^^ + +All you have to to is to adjust the path of :ref:`env_mysql_datadir` in the ``.env`` file. + +.. code-block:: bash + + # Navigate to Devilbox git directory + host> cd path/to/devilbox + + # Open the .env file with your favourite editor + host> vim .env + +Now Adjust the value of :ref:`env_mysql_datadir` + +.. code-block:: bash + :name: .env + :caption: .env + :emphasize-lines: 1 + + HOST_PATH_MYSQL_DATADIR=/home/user/workspace/db/mysql + +That's it, whenever you start up the Devilbox ``/home/user/workspace/db/mysql/`` will be mounted +into the MySQL container. + +PostgreSQL +^^^^^^^^^^ + +All you have to to is to adjust the path of :ref:`env_pgsql_datadir` in the ``.env`` file. + +.. code-block:: bash + + # Navigate to Devilbox git directory + host> cd path/to/devilbox + + # Open the .env file with your favourite editor + host> vim .env + +Now Adjust the value of :ref:`env_pgsql_datadir` + +.. code-block:: bash + :name: .env + :caption: .env + :emphasize-lines: 1 + + HOST_PATH_PGSQL_DATADIR=/home/user/workspace/db/pgsql + +That's it, whenever you start up the Devilbox ``/home/user/workspace/db/pqsql/`` will be mounted +into the PostgreSQL container. + +MongoDB +^^^^^^^ + +All you have to to is to adjust the path of :ref:`env_mongo_datadir` in the ``.env`` file. + +.. code-block:: bash + + # Navigate to Devilbox git directory + host> cd path/to/devilbox + + # Open the .env file with your favourite editor + host> vim .env + +Now Adjust the value of :ref:`env_mongo_datadir` + +.. code-block:: bash + :name: .env + :caption: .env + :emphasize-lines: 1 + + HOST_PATH_MONGO_DATADIR=/home/user/workspace/db/mongo + +That's it, whenever you start up the Devilbox ``/home/user/workspace/db/mongo/`` will be mounted +into the MongoDB container. + + +Version control ``.env`` file +----------------------------- + +The ``.env`` file is ignored by git, because this is *your* file to customize and it should be +*your* responsibility to make sure to backup or version controlled. + +One concept you can apply here is to have a separate **dotfiles** git repository. +This is a repository that holds all of your configuration files such as vim, bash, zsh, xinit +and many more. Those files are usually stored inside this repository and then symlinked to the +correct location. By having all configuration files in one place, you can see and track changes +easily as well as bein able to jump back to previous configurations. + +In case of the Devilbox ``.env`` file, just store this file in your repository and symlink it to +the Devilbox git directiry. This way you make sure that you keep your file, even when the Devilbox +git directory is deleted and you also have a means of keeping track about changes you made. + + +Version control service config files +------------------------------------ + +.. todo:: This will require some changes on the Devilbox and will be implemented shortly. + + +symlink and have your own git directory + +Separate data partition, backups + + + +Timezone +======== + +The :ref:`env_timezone` value will affect PHP, web server and MySQL container equally. It does +however not affect any other official Docker container that are used within the Devilbox. This is +an issue that is currently still being worked on. + +Feel free to change this to any timezone you require for PHP and MySQL, but keep in mind that +timezone values for databases can be painful, once you want to switch to a different timezone. + +A good practice is to always use ``UTC`` on databases and have your front-end application calculate +the correct time for the user. This way you will be more independent of any changes. diff --git a/docs/index.rst b/docs/index.rst index e6bf1c6c..ddae1ccc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,6 +43,7 @@ host is ready to be served with your custom domain. getting-started/email-catch-all getting-started/enter-the-php-container getting-started/the-intranet + getting-started/best-practice .. toctree::