ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2024-12-21 21:57:47 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Extend getting started guide

Browse Source
This commit is contained in:
cytopia 2018-03-11 11:26:03 +01:00
parent 41d22a804d
commit 2180e8a287
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
14 changed files with 333 additions and 241 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/conf.py
View File

@ -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']

6
docs/getting-started/create-env-file.rst
View File

@ -1,6 +0,0 @@
****************
Create .env file
****************
Syncronize file permissions

100
docs/getting-started/docker-installation.rst
View File

@ -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
<br />

91
docs/getting-started/docker-toolbox.rst
View File

@ -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
<br />

160
docs/getting-started/install-the-devilbox.rst Normal file
View File

@ -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 <https://docs.docker.com/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.

39
docs/getting-started/installation.rst
View File

@ -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`

35
docs/getting-started/update-the-devilbox.rst Normal file
View File

@ -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
=======================

5
docs/index.rst
View File

@ -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

72
docs/installation/docker-installation.rst Normal file
View File

@ -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 <https://docs.docker.com/engine/installation/#supported-platforms>`_ for how to install ``Docker`` on your specific Linux distribution.
Docker on Windows
-----------------
Refer to the official `Docker for Windows documentation <https://docs.docker.com/docker-for-windows/install/>`_ for how to install ``Docker`` on Windows.
Docker on MacOS
---------------
Refer to the official `Docker for Mac documentation <https://docs.docker.com/docker-for-mac/install/>`_ 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 <https://docs.docker.com/compose/install/#install-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

55
docs/installation/docker-toolbox.rst Normal file
View File

@ -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 <https://docs.docker.com/toolbox/toolbox_install_windows/>`_ for how to install ``Docker Toolbox`` on Windows.
Docker Toolbox on MacOS
=======================
Refer to the official `Docker Toolbox on MacOS documentation <https://docs.docker.com/toolbox/toolbox_install_mac/>`_ 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

1
docs/installation/installation.md
View File

@ -1 +0,0 @@
# Installation

1
docs/installation/quickstart.md
View File

@ -1 +0,0 @@
# Quickstart

1
docs/installation/requirements.md
View File

@ -1 +0,0 @@
# Requirements

5
docs/readings/syncronize-container-permissions.rst Normal file
View File

@ -0,0 +1,5 @@
.. _syncronize_container_permissions:
********************************
Syncronize container permissions
********************************