diff --git a/docs/configuration-files/env-file.rst b/docs/configuration-files/env-file.rst index 392e23a6..07e53f35 100644 --- a/docs/configuration-files/env-file.rst +++ b/docs/configuration-files/env-file.rst @@ -11,13 +11,13 @@ variables parsed to docker-compose.yml. what is the `.env `_ file? -**Content** +**Table of Contents** .. contents:: :local: -General settings -================ +Core settings +============= DEBUG_COMPOSE_ENTRYPOINT ------------------------ @@ -39,6 +39,9 @@ DEVILBOX_PATH This specifies a relative or absolute path to the Devilbox git directory and will be used as a prefix for all Docker mount paths. +* Relative path: relative to the devilbox git directory (Must start with ``.``) +* Absolute path: Full path (Must start with ``/``) + The only reason you would ever want change this variable is when you are on MacOS and relocate your project files onto an NFS volume due to performance issues. @@ -82,15 +85,52 @@ colon (``:``). | | listen on all host computer interfaces / IP addresses | +------------------+-------------------------------------------------------------------------------+ +.. note:: + When using ``Docker Toolbox``, you must leave this variable empty, in order to have the exposed + ports available on the external interface of the virtual machine. + TLD_SUFFIX ---------- +This variable controls all of your projects domain suffix. ++----------------+------------------+---------------+ +| Name | Allowed values | Default value | ++================+==================+===============+ +| ``TLD_SUFFIX`` | alpha-num string | ``loc`` | ++----------------+------------------+---------------+ + +Your project domains are built together out of the project directory name and the ``TLD_SUFFIX``. +The formula is like this: ``http://.``. + +You can even use official tld's and have your nameserver point to an internal LAN id, to make +this project visible to everyone in your corporate LAN. + +**How does it look?** + ++-------------+----------------+---------------------------+ +| Project dir | ``TLD_SUFFIX`` | Project URL | ++=============+================+===========================+ +| my-test | ``loc`` | ``http://my-test.loc`` | ++-------------+----------------+---------------------------+ +| example | ``loc`` | ``http://example.loc`` | ++-------------+----------------+---------------------------+ +| www.test | ``loc`` | ``http://www.test.loc`` | ++-------------+----------------+---------------------------+ +| my-test | ``local`` | ``http://my-test.local`` | ++-------------+----------------+---------------------------+ +| example | ``local`` | ``http://example.local`` | ++-------------+----------------+---------------------------+ +| www.test | ``local`` | ``http://www.test.local`` | ++-------------+----------------+---------------------------+ +| my-test | ``net`` | ``http://my-test.net`` | ++-------------+----------------+---------------------------+ +| example | ``com`` | ``http://example.com`` | ++-------------+----------------+---------------------------+ +| www.test | ``org`` | ``http://www.test.org`` | ++-------------+----------------+---------------------------+ -.. note:: - When using ``Docker Toolbox``, you must leave this variable empty, in order to have the exposed - ports available on the external interface of the virtual machine. .. _env_new_uid: @@ -173,3 +213,382 @@ Have a look at Wikipedia to get a list of valid timezones: https://en.wikipedia. .. note:: It is always a good practice not to assume a specific timezone anyway and store all values in UTC (such as time types in MySQL). + + +Intranet settings +================= + + +DNS_CHECK_TIMEOUT +----------------- + +The Devilbox intranet validates if every project has a corresponding DNS record (either an official +DNS record, one that came from its own Auto-DNS or an ``/etc/hosts`` entry). By doing so it queries +the DNS record based on ``.``. In case it does not exist, the query itself +might take a while and the intranet page will be unresponsive during that time. In order to avoid +long waiting times, you can set the DNS query time-out in seconds after which the query should stop +and report as unsuccessful. The default is ``1`` second, wich should be fairly sane for all use-cases. + ++-----------------------+----------------+-------------------+ +| Name | Allowed values | Default value | ++=======================+================+===================+ +| ``DNS_CHECK_TIMEOUT`` | integers | ``1`` | ++-----------------------+----------------+-------------------+ + + + + +DEVILBOX_UI_PROTECT +------------------- + +By setting this variable to ``1``, the Devilbox intranet will be password protected. +This might be useful, if you share your running Devilbox instance accross a LAN, but do not want +everybody to have access to the intranet itself, just to the projects you actually provide. + ++-------------------------+----------------+-------------------+ +| Name | Allowed values | Default value | ++=========================+================+===================+ +| ``DEVILBOX_UI_PROTECT`` | ``0`` or ``1`` | ``0`` | ++-------------------------+----------------+-------------------+ + +.. note:: + Also pay attention to the next env var, which will control the password for the login: + ``DEVILBOX_UI_PASSWORD``. + + +DEVILBOX_UI_PASSWORD +-------------------- + +When the devilbox intranet is password-protected via ``DEVILBOX_UI_PROTECT``, this is the actual +password by which it will be protected. + ++--------------------------+----------------+-------------------+ +| Name | Allowed values | Default value | ++==========================+================+===================+ +| ``DEVILBOX_UI_PASSWORD`` | any string | ``password`` | ++--------------------------+----------------+-------------------+ + + +DEVILBOX_UI_DISABLE +------------------- + +In case you want to completely disable the Devilbox intranet, such as when running it on production, +you need to set this variable to ``1``. + +By disabling the intranet, the webserver will simply remove the default virtual host and redirect +all IP-based requests to the first available virtual host, which will be you first project when +ordering their names alphabetically. + ++-------------------------+----------------+-------------------+ +| Name | Allowed values | Default value | ++=========================+================+===================+ +| ``DEVILBOX_UI_DISABLE`` | ``0`` or ``1`` | ``0`` | ++-------------------------+----------------+-------------------+ + + +Docker image versions +===================== + +The following settings reflect one of the main goals of the Devilbox: being able to run any +combination of all container versions. + +.. note:: + Any change for those settings requires a restart of the devilbox. + + +PHP_SERVER +---------- + +This variable choses your desired PHP-FPM version to be started. + ++-------------------------+--------------------------------------------------------------------------------------------------------------------------+-----------------+ +| Name | Allowed values | Default value | ++=========================+==========================================================================================================================+=================+ +| ``PHP_SERVER`` | ``php-fpm-5.4`` |br| ``php-fpm-5.5`` |br| ``php-fpm-5.6`` |br| ``php-fpm-7.0`` |br| ``php-fpm-7.1`` |br| ``php-fpm-7.2`` | ``php-fpm-7.1`` | ++-------------------------+--------------------------------------------------------------------------------------------------------------------------+-----------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 7 + + host> grep PHP_SERVER .env + + #PHP_SERVER=php-fpm-5.4 + #PHP_SERVER=php-fpm-5.5 + #PHP_SERVER=php-fpm-5.6 + #PHP_SERVER=php-fpm-7.0 + PHP_SERVER=php-fpm-7.1 + #PHP_SERVER=php-fpm-7.2 + #PHP_SERVER=php-fpm-7.3 + #PHP_SERVER=hhvm-latest + + +HTTPD_SERVER +------------ + +This variable choses your desired web server version to be started. + ++-------------------------+----------------------------------------------------------------------------------+------------------+ +| Name | Allowed values | Default value | ++=========================+==================================================================================+==================+ +| ``HTTPD_SERVER`` | ``apache-2.2`` |br| ``apache-2.4`` |br| ``nginx-stable`` |br| ``nginx-mainline`` | ``nginx-stable`` | ++-------------------------+----------------------------------------------------------------------------------+------------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 5 + + host> grep HTTPD_SERVER .env + + #HTTPD_SERVER=apache-2.2 + #HTTPD_SERVER=apache-2.4 + HTTPD_SERVER=nginx-stable + #HTTPD_SERVER=nginx-mainline + + +MYSQL_SERVER +------------ + +This variable choses your desired MySQL server version to be started. + ++-------------------------+------------------------------------------------------------------------------------------------+------------------+ +| Name | Allowed values | Default value | ++=========================+================================================================================================+==================+ +| ``MYSQL_SERVER`` | ``mysql-5.5`` |br| ``mysql-5.6`` |br| ``mariadb-10.2`` |br| ``percona-5.7`` |br| and many more | ``mariadb-10.1`` | ++-------------------------+------------------------------------------------------------------------------------------------+------------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 9 + + host> grep MYSQL_SERVER .env + + #MYSQL_SERVER=mysql-5.5 + #MYSQL_SERVER=mysql-5.6 + #MYSQL_SERVER=mysql-5.7 + #MYSQL_SERVER=mysql-8.0 + #MYSQL_SERVER=mariadb-5.5 + #MYSQL_SERVER=mariadb-10.0 + MYSQL_SERVER=mariadb-10.1 + #MYSQL_SERVER=mariadb-10.2 + #MYSQL_SERVER=mariadb-10.3 + #MYSQL_SERVER=percona-5.5 + #MYSQL_SERVER=percona-5.6 + #MYSQL_SERVER=percona-5.7 + + +PGSQL_SERVER +------------ + +This variable choses your desired PostgreSQL server version to be started. + ++-------------------------+-------------------------------------------------------------------+------------------+ +| Name | Allowed values | Default value | ++=========================+===================================================================+==================+ +| ``PGSQL_SERVER`` | ``9.1`` |br| ``9.2`` |br| ``9.3`` |br| ``9.4`` |br| and many more | ``9.6`` | ++-------------------------+-------------------------------------------------------------------+------------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 8 + + host> grep PGSQL_SERVER .env + + #PGSQL_SERVER=9.1 + #PGSQL_SERVER=9.2 + #PGSQL_SERVER=9.3 + #PGSQL_SERVER=9.4 + #PGSQL_SERVER=9.5 + PGSQL_SERVER=9.6 + #PGSQL_SERVER=10.0 + +.. note:: + This is the official PostgreSQL server which might already have other tags available, + check their official website for even more versions. + https://hub.docker.com/_/postgres/ + + +REDIS_SERVER +------------ + +This variable choses your desired Redis server version to be started. + ++-------------------------+-------------------------------------------------------------------+------------------+ +| Name | Allowed values | Default value | ++=========================+===================================================================+==================+ +| ``REDIS_SERVER`` | ``2.8`` |br| ``3.0`` |br| ``3.2`` |br| ``4.0`` |br| and many more | ``4.0`` | ++-------------------------+-------------------------------------------------------------------+------------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 6 + + host> grep REDIS_SERVER .env + + #REDIS_SERVER=2.8 + #REDIS_SERVER=3.0 + #REDIS_SERVER=3.2 + REDIS_SERVER=4.0 + +.. note:: + This is the official Redis server which might already have other tags available, + check their official website for even more versions. + https://hub.docker.com/_/redis/ + + +MEMCD_SERVER +------------ + +This variable choses your desired Memcached server version to be started. + ++-------------------------+-------------------------------------------------------------------------------+------------------+ +| Name | Allowed values | Default value | ++=========================+===============================================================================+==================+ +| ``MEMCD_SERVER`` | ``1.4.21`` |br| ``1.4.22`` |br| ``1.4.23`` |br| ``1.4.24`` |br| and many more | ``1.5.2`` | ++-------------------------+-------------------------------------------------------------------------------+------------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 24 + + host> grep MEMCD_SERVER .env + + #MEMCD_SERVER=1.4.21 + #MEMCD_SERVER=1.4.22 + #MEMCD_SERVER=1.4.23 + #MEMCD_SERVER=1.4.24 + #MEMCD_SERVER=1.4.25 + #MEMCD_SERVER=1.4.26 + #MEMCD_SERVER=1.4.27 + #MEMCD_SERVER=1.4.28 + #MEMCD_SERVER=1.4.29 + #MEMCD_SERVER=1.4.30 + #MEMCD_SERVER=1.4.31 + #MEMCD_SERVER=1.4.32 + #MEMCD_SERVER=1.4.33 + #MEMCD_SERVER=1.4.34 + #MEMCD_SERVER=1.4.35 + #MEMCD_SERVER=1.4.36 + #MEMCD_SERVER=1.4.37 + #MEMCD_SERVER=1.4.38 + #MEMCD_SERVER=1.4.39 + #MEMCD_SERVER=1.5.0 + #MEMCD_SERVER=1.5.1 + MEMCD_SERVER=1.5.2 + #MEMCD_SERVER=latest + +.. note:: + This is the official Memcached server which might already have other tags available, + check their official website for even more versions. + https://hub.docker.com/_/memcached/ + + +MONGO_SERVER +------------ + +This variable choses your desired MongoDB server version to be started. + ++-------------------------+-------------------------------------------------------------------+------------------+ +| Name | Allowed values | Default value | ++=========================+===================================================================+==================+ +| ``MONGO_SERVER`` | ``2.8`` |br| ``3.0`` |br| ``3.2`` |br| ``3.4`` |br| and many more | ``3.4`` | ++-------------------------+-------------------------------------------------------------------+------------------+ + +All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 6 + + host> grep MONGO_SERVER .env + + #MONGO_SERVER=2.8 + #MONGO_SERVER=3.0 + #MONGO_SERVER=3.2 + MONGO_SERVER=3.4 + #MONGO_SERVER=3.5 + +.. note:: + This is the official MongoDB server which might already have other tags available, + check their official website for even more versions. + https://hub.docker.com/_/mongo/ + + +Docker host mounts +================== + +The Docker host mounts are directory paths on your host operating system that will be mounted into +the running Docker container. This makes data persistent accross restarts and let them be available +on both sides: Your host operating system as well as inside the container. + +This also gives you the choice to edit data on your host operating system, such as with your +favourite IDE/editor and also inside the container, by using the bundled tools, such as +downloading libraries with ``composer`` and others. + +Being able to do that on both sides, removes the need to install any development tools (except your +IDE/editor) on your host and have everything fully encapsulated into the containers itself. + + +HOST_PATH_HTTPD_DATADIR +----------------------- + +This is an absolute or relative path (relative to Devilbox git directory) to your data directory. + +.. seealso:: + :ref:`getting_started_directory_overview_datadir` + +By default, all of your websites/projects will be stored in that directory. If however you want +to separate your data from the Devilbox git directory, do change the path to a place where you +want to store all of your projects on your host computer. + +* Relative path: relative to the devilbox git directory (Must start with ``.``) +* Absolute path: Full path (Must start with ``/``) + ++------------------------------+----------------+----------------+ +| Name | Allowed values | Default value | ++==============================+================+================+ +| ``HOST_PATH_HTTPD_DATADIR`` | valid path | ``./data/www`` | ++------------------------------+----------------+----------------+ + +Example +^^^^^^^ + +If you want to move all your projects to ``/home/myuser/workspace/web/`` for example, just set it +like this: + +.. code-block:: bash + :caption: .env + :name: .env + + HOST_PATH_HTTPD_DATADIR=/home/myuser/workspace/web + +Mapping +^^^^^^^ + +No matter what path you assign, inside the PHP and the web server container your data dir will +always be ``/shared/httpd/``. + + + +.. |br| raw:: html + +
diff --git a/docs/getting-started/create-your-first-project.rst b/docs/getting-started/create-your-first-project.rst index 19e1c303..42d45d89 100644 --- a/docs/getting-started/create-your-first-project.rst +++ b/docs/getting-started/create-your-first-project.rst @@ -1,3 +1,5 @@ +.. _getting_started_create_your_first_project: + ************************* Create your first project ************************* @@ -7,132 +9,14 @@ Create your first project This section not only applies for one project, it applied for as many projects as you need. **There is no limit in the number of projects.** -.. _prerequisites: -Prerequisites -============= +**Table of Contents** -.. important:: - The prerequisites section only provides you some theoretical, but useful insights about how - it all works together. You should at least read it once to be able to debug any problems you - might encounter. +.. contents:: :local: -If you have read it already, jump directly to :ref:`project_creation_workflow` - - -Data directory --------------- - -By default all your projects must be created in the ``./data/www/`` directory which is inside in -your Devilbox git directory. This can be changed as well, but is outside the scope of this -*getting started tutorial*. - -You can verifiy that the path is actually ``./data/www/`` by checking your ``.env`` file: - -.. code-block:: bash - - host> grep HTTPD_DATADIR .env - - HOST_PATH_HTTPD_DATADIR=./data/www - - -Project directory ------------------ - -The project directory is a directory directly within the data directory. - -**This represents one project.** - -By creating this directory, the web server will create a new virtual host for you. This -happens fully automated and there is nothing else required to do except just to create a directory. - -The name of this directory will also be used to build up the final project url together with the -domain suffix: ``http://.`` - -Create as many project directories as you require. - - -Docroot directory ------------------ - -The docroot directory is a directory within each project directory from which the webserver will serve the files. - -By default this directory must be named ``htdocs``. This can be changed as well, but is outside -the scope of this *getting started tutorial*. - -You can verifiy that the docroot directory is actually ``htdocs`` by checking your ``.env`` file: - -.. code-block:: bash - - host> grep DOCROOT_DIR .env - - - HTTPD_DOCROOT_DIR=htdocs - - -Domain suffix -------------- - -The default domain suffix (``TLD_SUFFIX`` variable in ``.env`` file) is ``loc``. That means that -all your projects will be available under the following address: ``http://.loc``. -This can be changed as well, but is outside the scope of this *getting started tutorial*. - -You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` file: - -.. code-block:: bash - - host> grep ^TLD_SUFFIX .env - - TLD_SUFFIX=loc - - -Making sense of it ------------------- - -Ok, let's sum it up and make sense of the previously provided information. To better illustrate -the behaviour we are going to use ``project-1`` as our project directory name. - -+---------------+---------------------------------+-------------------------------------------------------------+ -| Item | Example | Description | -+===============+=================================+=============================================================+ -| data dir | ``./data/www`` | Where all of your projects reside. | -+---------------+---------------------------------+-------------------------------------------------------------+ -| project dir | ``./data/www/project-1`` | A single project. It's name will be used to create the url. | -+---------------+---------------------------------+-------------------------------------------------------------+ -| docroot dir | ``./data/www/project-1/htdocs`` | Where the webserver looks for files within your project. | -+---------------+---------------------------------+-------------------------------------------------------------+ -| domain suffix | ``loc`` | Suffix to build up your project url. | -+---------------+---------------------------------+-------------------------------------------------------------+ -| project url | ``http://project-1.loc`` | Final resulting project url. | -+---------------+---------------------------------+-------------------------------------------------------------+ - -**data dir** - -This directory is mounted into the ``httpd`` and ``php`` container, so that both know where all projects can be found. This is also the place where you create ``project directories`` for each of your projects. - -**project dir** - -Is your project and used to generate the virtual host together with the domain suffix. - -**docroot dir** - -A directory inside your ``project dir`` from where the webserver will actually serve your files. - -**domain suffix** - -Used as part of the project url. - -.. note:: - The projcet directory will be discussed in more detail in :ref:`project_creation_workflow` below. - - -.. _project_creation_workflow: - -Project creation workflow -========================= Step 1: visit Intranet vhost page ---------------------------------- +================================= Before starting, have a look at the vhost page at http://localhost/vhosts.php @@ -142,7 +26,7 @@ It should look like the screenshot below and will actually already provide the i Step 2: create a project directory ----------------------------------- +================================== In your Devilbox git directory, navigate to ``./data/www`` and create a new directory. @@ -169,11 +53,12 @@ Vist the vhost page again and see what has changed: http://localhost/vhosts.php By having created a project directory, the web server container has created a new virtual host. However it has noticed, that the actual document root directory does not yet exist and therefore it cannot serve any files yet. + Step 3: create a docroot directory ----------------------------------- +================================== .. note:: - As desribed in :ref:`prerequisites` the docroot directory name must be ``htdocs`` for now. + As desribed in :ref:`getting_started_directory_overview_docroot` the docroot directory name must be ``htdocs`` for now. Navigate to your newly created project directory and create a directory named `htdocs` inside it. @@ -201,8 +86,9 @@ The intranet already gives you the exact string that you can simply copy into yo .. important:: This will only work on **native Docker** for Linux or MacOS. Read up on the next section to also find out how to do that on **Docker Toolbox** and Windows. + Step 4: create a DNS entry --------------------------- +========================== .. note:: This step can also be automated via the bundled DNS server to automatically provide catch-all @@ -210,7 +96,7 @@ Step 4: create a DNS entry *getting started tutorial*. Add DNS for Linux and MacOS (native Docker) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +------------------------------------------- On Linux and MacOS (when using the native Docker), this step is fairly simple. The intranet provides you the exact string you need to paste into your ``/etc/hosts`` file on your host operating system. @@ -224,7 +110,7 @@ you the exact string you need to paste into your ``/etc/hosts`` file on your hos 127.0.0.1 project-1.loc Add DNS for Windows (native Docker) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +----------------------------------- On Windows (when using the native Docker), you can also copy paste the command provided by the intranet, however the destination file is different. You have to add this string into: ``C:\Windows\System32\drivers\etc``. @@ -236,7 +122,7 @@ Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add th 127.0.0.1 project-1.loc Add DNS for Docker Toolbox -^^^^^^^^^^^^^^^^^^^^^^^^^^ +-------------------------- When using ``Docker Toolbox`` the Devilbox runs inside a virtual machine and therefore the Webserver port (``80``) is not exposed to your host operating system. So your DNS record must point to the virtual machine instead of your @@ -264,9 +150,8 @@ Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add th 192.16.0.1 project-1.loc - Back to intranet -^^^^^^^^^^^^^^^^ +---------------- Vist the vhost page again and see what has changed: http://localhost/vhosts.php @@ -277,8 +162,9 @@ Vist the vhost page again and see what has changed: http://localhost/vhosts.php By having created the DNS record, the Devilbox intranet is aware that everything is setup now and gives you a link to your new project. + Step 5: Visit your project --------------------------- +========================== On the intranet, click on your project link. This will open your project in a new Browser tab or visit http://project-1.loc @@ -291,8 +177,9 @@ Everything is setup now, however the webserver is trying to find a ``index.php`` So all is left for you to do is to add your HTML or PHP files. + Step 6: Create a hello world ----------------------------- +============================ Navigate to your docroot directory within your project and create a ``index.php`` file with some output. @@ -321,8 +208,7 @@ Vist your project url again and see what has changed: http://project-1.loc Checklist ========= -1. :ref:`prerequisites` are read and understood -2. Project directory is created -3. Docroot directory is created -4. DNS entry is added to the host operating system -5. PHP files are added to your docroot directory +1. Project directory is created +2. Docroot directory is created +3. DNS entry is added to the host operating system +4. PHP files are added to your docroot directory diff --git a/docs/getting-started/directory-overview.rst b/docs/getting-started/directory-overview.rst new file mode 100644 index 00000000..37968251 --- /dev/null +++ b/docs/getting-started/directory-overview.rst @@ -0,0 +1,133 @@ +.. _getting_started_directory_overview: + +****************** +Directory overview +****************** + +.. important:: + The directory overview only provides you some theoretical, but useful insights about how + it all works together. You should at least read it once to be able to debug any problems you + might encounter. + +If you have read it already, jump directly to :ref:`getting_started_create_your_first_project` + + +**Table of Contents** + +.. contents:: :local: + + +.. _getting_started_directory_overview_datadir: + +Data directory +============== + +By default all your projects must be created in the ``./data/www/`` directory which is inside in +your Devilbox git directory. This can be changed as well, but is outside the scope of this +*getting started tutorial*. + +You can verifiy that the path is actually ``./data/www/`` by checking your ``.env`` file: + +.. code-block:: bash + + host> grep HTTPD_DATADIR .env + + HOST_PATH_HTTPD_DATADIR=./data/www + + +Project directory +================= + +The project directory is a directory directly within the data directory. + +**This represents one project.** + +By creating this directory, the web server will create a new virtual host for you. This +happens fully automated and there is nothing else required to do except just to create a directory. + +The name of this directory will also be used to build up the final project url together with the +domain suffix: ``http://.`` + +Create as many project directories as you require. + +.. _getting_started_directory_overview_docroot: + +Docroot directory +================= + +The docroot directory is a directory within each project directory from which the webserver will serve the files. + +By default this directory must be named ``htdocs``. This can be changed as well, but is outside +the scope of this *getting started tutorial*. + +You can verifiy that the docroot directory is actually ``htdocs`` by checking your ``.env`` file: + +.. code-block:: bash + + host> grep DOCROOT_DIR .env + + + HTTPD_DOCROOT_DIR=htdocs + + +Domain suffix +============= + +The default domain suffix (``TLD_SUFFIX`` variable in ``.env`` file) is ``loc``. That means that +all your projects will be available under the following address: ``http://.loc``. +This can be changed as well, but is outside the scope of this *getting started tutorial*. + +You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` file: + +.. code-block:: bash + + host> grep ^TLD_SUFFIX .env + + TLD_SUFFIX=loc + + +Making sense of it +================== + +Ok, let's sum it up and make sense of the previously provided information. To better illustrate +the behaviour we are going to use ``project-1`` as our project directory name. + ++---------------+---------------------------------+-------------------------------------------------------------+ +| Item | Example | Description | ++===============+=================================+=============================================================+ +| data dir | ``./data/www`` | Where all of your projects reside. | ++---------------+---------------------------------+-------------------------------------------------------------+ +| project dir | ``./data/www/project-1`` | A single project. It's name will be used to create the url. | ++---------------+---------------------------------+-------------------------------------------------------------+ +| docroot dir | ``./data/www/project-1/htdocs`` | Where the webserver looks for files within your project. | ++---------------+---------------------------------+-------------------------------------------------------------+ +| domain suffix | ``loc`` | Suffix to build up your project url. | ++---------------+---------------------------------+-------------------------------------------------------------+ +| project url | ``http://project-1.loc`` | Final resulting project url. | ++---------------+---------------------------------+-------------------------------------------------------------+ + +**data dir** + +This directory is mounted into the ``httpd`` and ``php`` container, so that both know where all projects can be found. This is also the place where you create ``project directories`` for each of your projects. + +**project dir** + +Is your project and used to generate the virtual host together with the domain suffix. + +**docroot dir** + +A directory inside your ``project dir`` from where the webserver will actually serve your files. + +**domain suffix** + +Used as part of the project url. + + +Checklist +========= + +1. You know what the data directory is +2. You know what the project directory is +3. You know what the docroot directory is +4. You know what the domain suffix is +5. You know how domains are constructed diff --git a/docs/getting-started/install-the-devilbox.rst b/docs/getting-started/install-the-devilbox.rst index ecef8724..d9e1cc67 100644 --- a/docs/getting-started/install-the-devilbox.rst +++ b/docs/getting-started/install-the-devilbox.rst @@ -7,6 +7,11 @@ Install the Devilbox Ensure you have read this document to understand how this documentation works. +**Table of Contents** + +.. contents:: :local: + + Supported OS ============ diff --git a/docs/getting-started/start-the-devilbox.rst b/docs/getting-started/start-the-devilbox.rst index cc3362ac..280c8f56 100644 --- a/docs/getting-started/start-the-devilbox.rst +++ b/docs/getting-started/start-the-devilbox.rst @@ -16,6 +16,11 @@ hands dirty. `stop `_ commands. +**Table of Contents** + +.. contents:: :local: + + Start all container =================== diff --git a/docs/getting-started/update-the-devilbox.rst b/docs/getting-started/update-the-devilbox.rst index 4120355b..043a48a8 100644 --- a/docs/getting-started/update-the-devilbox.rst +++ b/docs/getting-started/update-the-devilbox.rst @@ -5,6 +5,12 @@ Update the Devilbox If you are in the initial install process, you can safely skip this section and come back once you actually want to update the Devilbox. + +**Table of Contents** + +.. contents:: :local: + + Update git repository ===================== diff --git a/docs/index.rst b/docs/index.rst index e67bc7a4..efb875e3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ devilbox documentation getting-started/install-the-devilbox getting-started/update-the-devilbox getting-started/start-the-devilbox + getting-started/directory-overview getting-started/create-your-first-project