From 2180e8a28704540ac6a7cf236763dda14dee10f8 Mon Sep 17 00:00:00 2001 From: cytopia Date: Sun, 11 Mar 2018 11:26:03 +0100 Subject: [PATCH] Extend getting started guide --- docs/conf.py | 3 + docs/getting-started/create-env-file.rst | 6 - docs/getting-started/docker-installation.rst | 100 ----------- docs/getting-started/docker-toolbox.rst | 91 ---------- docs/getting-started/install-the-devilbox.rst | 160 ++++++++++++++++++ docs/getting-started/installation.rst | 39 ----- docs/getting-started/update-the-devilbox.rst | 35 ++++ docs/index.rst | 5 +- docs/installation/docker-installation.rst | 72 ++++++++ docs/installation/docker-toolbox.rst | 55 ++++++ docs/installation/installation.md | 1 - docs/installation/quickstart.md | 1 - docs/installation/requirements.md | 1 - .../syncronize-container-permissions.rst | 5 + 14 files changed, 333 insertions(+), 241 deletions(-) delete mode 100644 docs/getting-started/create-env-file.rst delete mode 100644 docs/getting-started/docker-installation.rst delete mode 100644 docs/getting-started/docker-toolbox.rst create mode 100644 docs/getting-started/install-the-devilbox.rst delete mode 100644 docs/getting-started/installation.rst create mode 100644 docs/getting-started/update-the-devilbox.rst create mode 100644 docs/installation/docker-installation.rst create mode 100644 docs/installation/docker-toolbox.rst delete mode 100644 docs/installation/installation.md delete mode 100644 docs/installation/quickstart.md delete mode 100644 docs/installation/requirements.md create mode 100644 docs/readings/syncronize-container-permissions.rst diff --git a/docs/conf.py b/docs/conf.py index bf02fb2c..9c6234d4 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,8 +44,11 @@ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.todo' ] +todo_include_todos = True + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/getting-started/create-env-file.rst b/docs/getting-started/create-env-file.rst deleted file mode 100644 index 3efe0e61..00000000 --- a/docs/getting-started/create-env-file.rst +++ /dev/null @@ -1,6 +0,0 @@ -**************** -Create .env file -**************** - - -Syncronize file permissions diff --git a/docs/getting-started/docker-installation.rst b/docs/getting-started/docker-installation.rst deleted file mode 100644 index dc986213..00000000 --- a/docs/getting-started/docker-installation.rst +++ /dev/null @@ -1,100 +0,0 @@ -************** -Install Docker -************** - -.. _install_docker: - -Install Docker -============== - - -.. _install_docker_compose: - -Install Docker Compose -====================== - -Before going to proceed with the devilbox installation and setup, make sure you meet the requirements. - -Requirements -============ - -Both ``Docker`` and ``Docker Compose`` is required for the devilbox to work. Whether you go with the -recommended or not recommended Docker version is up to you. Most important part is to pay attention to -the version number. - -You **must** have at least the following versions or above: - -* ``Docker``: 1.12.0 -* ``Docker Compose``: 1.9.0 - -Additionally you require ``git`` in order to clone the devilbox project later on. - - -Recommended Docker versions ---------------------------- - -Do use native Docker and do not rely on Docker Toolbox whenever possible. - -+--------------------+------------------------+----------------------------+------------------------+ -| | |logo_lin| | |logo_win| | |logo_osx| | -+====================+========================+============================+========================+ -| **Docker** | `Docker`_ |br| | `Docker for Windows`_ |br| | `Docker for Mac`_ |br| | -| | 1.12.0+ | 1.12.0+ | 1.12.0+ | -+--------------------+------------------------+----------------------------+------------------------+ -| **Docker Compose** | `Docker Compose`_ |br| | `Docker Compose`_ |br| | `Docker Compose`_ |br| | -| | 1.9.0+ | 1.9.0+ | 1.9.0+ | -+--------------------+------------------------+----------------------------+------------------------+ - -.. |logo_lin| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png -.. |logo_osx| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png -.. |logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png -.. _Docker: https://docs.docker.com/install -.. _Docker for Windows: https://docs.docker.com/docker-for-windows/install -.. _Docker for Mac: https://docs.docker.com/docker-for-mac/install -.. _Docker Compose: https://docs.docker.com/compose/install/ - -Not recommended Docker versions -------------------------------- - -In case you are not able to use a native Docker versions (such as on Windows 7), your only chance -is to install the ``Docker Toolbox``. - -Validate installed versions ---------------------------- - -If you are going with the supported or unsupported Docker versions is up to you - -Once you have installed Docker and Docker Compose, ensure you have the required minimum version. - -.. code-block:: bash - - $ docker version - - - Client: - Version: 18.02.0-ce - API version: 1.36 - Go version: go1.9.3 - Git commit: fc4de44 - Built: Wed Feb 7 21:16:24 2018 - OS/Arch: linux/amd64 - Experimental: false - Orchestrator: swarm - - Server: - Engine: - Version: 18.02.0-ce - API version: 1.36 (minimum version 1.12) - Go version: go1.9.3 - Git commit: fc4de44 - Built: Wed Feb 7 21:14:54 2018 - OS/Arch: linux/amd64 - Experimental: false - -Supported versions ------------------- - - -.. |br| raw:: html - -
diff --git a/docs/getting-started/docker-toolbox.rst b/docs/getting-started/docker-toolbox.rst deleted file mode 100644 index 0e051c95..00000000 --- a/docs/getting-started/docker-toolbox.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _docker_toolbox: - -************** -Docker Toolbox -************** - -Before going to proceed with the devilbox installation and setup, make sure you meet the requirements. - -Requirements -============ - -Both ``Docker`` and ``Docker Compose`` is required for the devilbox to work. Whether you go with the -recommended or not recommended Docker version is up to you. Most important part is to pay attention to -the version number. - -You **must** have at least the following versions or above: - -* ``Docker``: 1.12.0 -* ``Docker Compose``: 1.9.0 - -Additionally you require ``git`` in order to clone the devilbox project later on. - - -Recommended Docker versions ---------------------------- - -Do use native Docker and do not rely on Docker Toolbox whenever possible. - -+--------------------+------------------------+----------------------------+------------------------+ -| | |logo_lin| | |logo_win| | |logo_osx| | -+====================+========================+============================+========================+ -| **Docker** | `Docker`_ |br| | `Docker for Windows`_ |br| | `Docker for Mac`_ |br| | -| | 1.12.0+ | 1.12.0+ | 1.12.0+ | -+--------------------+------------------------+----------------------------+------------------------+ -| **Docker Compose** | `Docker Compose`_ |br| | `Docker Compose`_ |br| | `Docker Compose`_ |br| | -| | 1.9.0+ | 1.9.0+ | 1.9.0+ | -+--------------------+------------------------+----------------------------+------------------------+ - -.. |logo_lin| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png -.. |logo_osx| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png -.. |logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png -.. _Docker: https://docs.docker.com/install -.. _Docker for Windows: https://docs.docker.com/docker-for-windows/install -.. _Docker for Mac: https://docs.docker.com/docker-for-mac/install -.. _Docker Compose: https://docs.docker.com/compose/install/ - -Not recommended Docker versions -------------------------------- - -In case you are not able to use a native Docker versions (such as on Windows 7), your only chance -is to install the ``Docker Toolbox``. - -Validate installed versions ---------------------------- - -If you are going with the supported or unsupported Docker versions is up to you - -Once you have installed Docker and Docker Compose, ensure you have the required minimum version. - -.. code-block:: bash - - $ docker version - - - Client: - Version: 18.02.0-ce - API version: 1.36 - Go version: go1.9.3 - Git commit: fc4de44 - Built: Wed Feb 7 21:16:24 2018 - OS/Arch: linux/amd64 - Experimental: false - Orchestrator: swarm - - Server: - Engine: - Version: 18.02.0-ce - API version: 1.36 (minimum version 1.12) - Go version: go1.9.3 - Git commit: fc4de44 - Built: Wed Feb 7 21:14:54 2018 - OS/Arch: linux/amd64 - Experimental: false - -Supported versions ------------------- - - -.. |br| raw:: html - -
diff --git a/docs/getting-started/install-the-devilbox.rst b/docs/getting-started/install-the-devilbox.rst new file mode 100644 index 00000000..52307696 --- /dev/null +++ b/docs/getting-started/install-the-devilbox.rst @@ -0,0 +1,160 @@ +******************** +Install the Devilbox +******************** + +Supported OS +============ + +The devilbox runs on all operating systems that provide ``Docker`` and ``Docker Compose``. + ++------------+------------+------------+ +| |logo_lin| | |logo_win| | |logo_osx| | ++------------+------------+------------+ + +.. |logo_lin| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png +.. |logo_osx| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png +.. |logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png + + +Requirements +============ + +The only requirements for the devilbox is to have ``Docker`` and ``Docker Compose`` installed, +everything else is bundled and provided withing the Docker container. +The minimum required versions are listed below: + +* ``Docker``: 1.12.0+ +* ``Docker Compose``: 1.9.0+ + + +Additionally you will require ``git`` in order to clone the devilbox project. + +.. warning:: + :ref:`docker_toolbox` + Use **native Docker** and do not use the **Docker Toolbox**. If you still have to use the + Docker Toolbox (e.g. for Windows 7 or older Macs) read up on this section. + +.. warning:: + Docker itself requires super user privileges which is granted to a system wide group + called ``docker``. After having installed Docker on your system, ensure that your local + user is assigned to the ``docker`` group. Check this via ``groups`` or ``id`` command. + +.. seealso:: + :ref:`install_docker` + Have a look at this page to help you install ``Docker`` for your operating system. + :ref:`install_docker_compose` + Have a look at this page to help you install ``Docker Compose`` for your operating system. + + +Download the devilbox +===================== + +The devilbox does not need to be installed. The only thing that is required is its git directory. +To download that, open a terminal and copy/paste the following command. + +.. code-block:: console + + git clone https://github.com/cytopia/devilbox + + +Checkout a different release +---------------------------- + +You now have the devilbox downloaded at the latest version (``git master branch``). This is also recommended as it receives +bugfixes frequently. If you however want to stay on a stable release, you need to check out s +specific ``git tag``. + +Lets say you want your devilbox setup to be at release ``0.12.1``, all you have to do is to check out +this specific git tag. + +.. code-block:: console + + cd path/to/devilbox + git checkout 0.12.1 + + +.. warning:: + Whenever you check out a different version, make sure that your ``.env`` file is up-to-date + with the bundled ``env-example`` file. Different Devilbox releases might require different + settings to be available inside the ``.env`` file. Refer to the next section for how to + create the ``.env`` file. + + +Create ``.env`` file +==================== + +Inside the cloned devilbox git directory, you will find a file called ``env-example``. This file +acts as a template with sane defaults for ``Docker Compose``. In order to use it, it must be +copied to a file named ``.env``. (Note the leading dot). + +.. code-block:: console + + cp env-example .env + +The ``.env`` file does nothing else then providing environment variables for ``Docker Compose`` +and in this case it is used as the main configuration file for the devilbox by providing all kinds +of settings (such as which version to start up). + +.. seealso:: `Docker Compose: env file `_ + + +Adjust ``.env`` file +==================== + +To get you started, there are only two variables that need to be adjusted: + +* ``NEW_UID`` +* ``NEW_GID`` + +The values for those two variables refer to your local (on your host operating system) user id +and group id. To find out what the values are required in your case, issue the following commands +on a terminal: + +Find your user id +----------------- + +.. code-block:: console + + id -u + +Find your group id +------------------ + +.. code-block:: console + + id -g + +In most cases both values will be ``1000``, but for the sake of this example, let's assume a value +of ``1001`` for the user id and ``1002`` for the group id. + +Open the ``.env`` file with your favorite text editor and adjust those values: + +.. code-block:: bash + :caption: .env + :name: .env + :emphasize-lines: 3,4 + + vi .env + + NEW_UID=1001 + NEW_GID=1002 + +.. warning:: + Make sure that you use the values provided by ``id -u`` and ``id -g``. + +.. seealso:: + :ref:`syncronize_container_permissions` + Read up more on the general problem of trying to have syncronized permissions between + the host system and a running Docker container. + + +Checklist +========= + +1. ``Docker`` and ``Docker Compose`` are installed at minimum required version +2. Your user is part of the ``docker`` group +3. ``Devilbox`` is cloned +4. ``.env`` file is created +5. User and group id have been set in ``.env`` file + +That's it, you have finished the first section and have a working Devilbox ready to be started. diff --git a/docs/getting-started/installation.rst b/docs/getting-started/installation.rst deleted file mode 100644 index 4b8c071f..00000000 --- a/docs/getting-started/installation.rst +++ /dev/null @@ -1,39 +0,0 @@ -************ -Installation -************ - -Install Requirements -==================== - -Both ``Docker`` and ``Docker Compose`` are required for the devilbox to run. They are -available for Linux, Windows and MacOS. Below are their minimum required versions: - -* ``Docker``: 1.12.0+ -* ``Docker Compose``: 1.9.0+ - - -Additionally you will require ``git`` in order to clone the devilbox project. - -.. warning:: - :ref:`docker_toolbox` - Use **native Docker** and do not use the **Docker Toolbox**. If you still have to use the - Docker Toolbox (e.g. for Windows 7) read up on this section. - - -Download the devilbox -===================== - -The devilbox does not need to be installed. The only thing that is required is its git directory. -To download that, open a terminal and copy/paste the following command. - -.. code-block:: console - - git clone https://github.com/cytopia/devilbox - -That's it, you have finished the first section. - - -.. seealso:: - * :ref:`install_docker` - * :ref:`install_docker_compose` - * :ref:`docker_toolbox` diff --git a/docs/getting-started/update-the-devilbox.rst b/docs/getting-started/update-the-devilbox.rst new file mode 100644 index 00000000..94fb91e5 --- /dev/null +++ b/docs/getting-started/update-the-devilbox.rst @@ -0,0 +1,35 @@ +******************* +Update the Devilbox +******************* + +Update git repository +===================== + +.. warning:: + Whenever you check out a different version, make sure that your ``.env`` file is up-to-date + with the bundled ``env-example`` file. Different Devilbox releases might require different + settings to be available inside the ``.env`` file. + +You can also compare your current ``.env`` file with the provided ``env-example`` file by using +your favorite diff editor: + +How to diff the ``.env`` file +----------------------------- + +.. code-block:: console + + vimdiff .env env-example + +.. code-block:: console + + diff .env env-example + +.. code-block:: console + + meld .env env-example + + + + +Update Docker container +======================= diff --git a/docs/index.rst b/docs/index.rst index 167fb159..e7b787ef 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,8 +12,8 @@ devilbox documentation :numbered: :caption: Getting started - getting-started/installation - getting-started/create-env-file + getting-started/install-the-devilbox + getting-started/update-the-devilbox getting-started/start-the-devilbox getting-started/create-your-first-project @@ -101,3 +101,4 @@ devilbox documentation support/faq support/contributing + support/artwork diff --git a/docs/installation/docker-installation.rst b/docs/installation/docker-installation.rst new file mode 100644 index 00000000..1887b6e6 --- /dev/null +++ b/docs/installation/docker-installation.rst @@ -0,0 +1,72 @@ +************************* +Docker and Docker Compose +************************* + +This section gives you some detail about installing ``Docker`` and ``Docker Compose`` on your +operating system. + +.. contents:: :local: + +.. _install_docker: + +Install Docker +============== + +.. seealso:: + :ref:`docker_toolbox` + Note, this section refers to **native Docker**, which is the recommended version. If however, + you need to install **Docker Toolbox** (such as on Windows 7 or older Macs), have a look at this page. + +.. warning:: + The minimum required ``Docker`` version is ``1.12.0``. Make sure not to install older versions. + + +Docker on Linux +--------------- + +Refer to the official `Docker for Linux documentation `_ for how to install ``Docker`` on your specific Linux distribution. + +Docker on Windows +----------------- + +Refer to the official `Docker for Windows documentation `_ for how to install ``Docker`` on Windows. + +Docker on MacOS +--------------- + +Refer to the official `Docker for Mac documentation `_ for how to install ``Docker`` on MacOS. + +``docker`` user group +--------------------- + +Docker itself requires super user privileges which is granted to a system wide group +called ``docker``. After having installed Docker on your system, ensure that your local +user is assigned to the ``docker`` group. Check this via ``groups`` or ``id`` command. + + +.. code-block:: console + + id + + uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker) + + + +.. _install_docker_compose: + +Install Docker Compose +====================== + +.. warning:: + The minimum required ``Docker Compose`` version is ``1.9.0``. Make sure not to install older versions. + +The Docker documentation provides various ways to install ``Docker Compose`` for all supported +operating systems and is quite extensive and straight forward. +Follow their steps here: `Install Docker Compose `_. + +Checklist +========= + +1. ``Docker`` is installed at the minimum required version +2. Your user is part of the ``docker`` group +3. ``Docker Compose`` is installed at the minimum required version diff --git a/docs/installation/docker-toolbox.rst b/docs/installation/docker-toolbox.rst new file mode 100644 index 00000000..f738000b --- /dev/null +++ b/docs/installation/docker-toolbox.rst @@ -0,0 +1,55 @@ +.. _docker_toolbox: + +************** +Docker Toolbox +************** + +.. contents:: :local: + + +``Docker Toolbox`` is a legacy solution to bring ``Docker`` to systems which don't natively support +Docker itself. This is achieved by starting a virtualized Linux (e.g.: on VirtualBox) and have Docker +run inside. + +You don't have to take care about setting up the virtual machine, this is done automatically with the provided +setup file (Windows and MacOS). + +This however has several disadvantages as the forwarded Docker ports are only visible inside the +virtualized Linux and not on the host computer. Therefore the web server port cannot be reached on +your host machine and you are not able to view any projects. + +This can be overcome by forwarding all ports from your virtual machine to your host computer. + +.. warning:: + The minimum required ``Docker Toolbox`` version is ``1.12.0``. Make sure not to install older versions. + +.. todo:: + + This section needs more details. + + +Docker Toolbox on Windows +========================= + +Refer to the official `Docker Toolbox on Windows documentation `_ for how to install ``Docker Toolbox`` on Windows. + + +Docker Toolbox on MacOS +======================= + +Refer to the official `Docker Toolbox on MacOS documentation `_ for how to install ``Docker Toolbox`` on MacOS. + +Docker Compose +============== + +When installing ``Docker Compose``, make sure you do that **inside the virtual machine**. + +.. seealso:: + :ref:`install_docker_compose` + Have a look at this page to help you install ``Docker Compose`` for your operating system. + +Checklist +========= + +1. ``Docker Toolbox`` is installed at minimum required version +2. ``Docker Compose`` is installed inside the virtual machine at minimum required version diff --git a/docs/installation/installation.md b/docs/installation/installation.md deleted file mode 100644 index 25267fe2..00000000 --- a/docs/installation/installation.md +++ /dev/null @@ -1 +0,0 @@ -# Installation diff --git a/docs/installation/quickstart.md b/docs/installation/quickstart.md deleted file mode 100644 index acb98436..00000000 --- a/docs/installation/quickstart.md +++ /dev/null @@ -1 +0,0 @@ -# Quickstart diff --git a/docs/installation/requirements.md b/docs/installation/requirements.md deleted file mode 100644 index 1fa9034a..00000000 --- a/docs/installation/requirements.md +++ /dev/null @@ -1 +0,0 @@ -# Requirements diff --git a/docs/readings/syncronize-container-permissions.rst b/docs/readings/syncronize-container-permissions.rst new file mode 100644 index 00000000..522f20d9 --- /dev/null +++ b/docs/readings/syncronize-container-permissions.rst @@ -0,0 +1,5 @@ +.. _syncronize_container_permissions: + +******************************** +Syncronize container permissions +********************************