mirror of
https://github.com/cytopia/devilbox.git
synced 2025-06-23 01:18:56 +00:00
Extend env file documentation
This commit is contained in:
cytopia
@ -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://<project directory>.<domain suffix>``
|
||||
|
||||
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://<project-directory>.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
|
||||
|
||||
133
docs/getting-started/directory-overview.rst
Normal file
133
docs/getting-started/directory-overview.rst
Normal file
@ -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://<project directory>.<domain suffix>``
|
||||
|
||||
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://<project-directory>.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
|
||||
@ -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
|
||||
============
|
||||
|
||||
|
||||
@ -16,6 +16,11 @@ hands dirty.
|
||||
`stop <https://docs.docker.com/compose/reference/stop/>`_ commands.
|
||||
|
||||
|
||||
**Table of Contents**
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
|
||||
Start all container
|
||||
===================
|
||||
|
||||
|
||||
@ -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
|
||||
=====================
|
||||
|
||||
|
||||
Reference in New Issue
Block a user