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

REL-0.9 Adding separate documentation

Browse Source
This commit is contained in:
cytopia 2017-05-06 11:12:54 +02:00
parent e58dee3984
commit 2f57691e58
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
11 changed files with 670 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
doc/Configuration.md Normal file
View File

@ -0,0 +1,113 @@
# Configuration
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
Configuration |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Configuration
### 1. The `.env` file
All docker-compose configuration is done inside the `.env` file which simply defines key-value variables parsed to `docker-compose.yml`.
First thing to do after cloning this repository is creating this file from the `env-example`.
```shell
$ cp env-example .env
```
The file itself is well commented and should explain itself. In case anything is unclear leave an issue at GitHub.
> [What is the `.env` file?](https://docs.docker.com/compose/env-file/)
There are a few sections you should be aware off to better understand how it all works.
#### 1.1 Selecting service versions
Each service has a `<SERVICE_NAME>_SERVER` variable with a corresponding version. All existing versions are present in the file and commented out.
It is important to leave at least one version uncomment, otherwise the start-up will lead to errors. Use the following variable to control which version will be loaded:
* **`PHP_SERVER`**
* **`HTTP_SERVER`**
* **`MYSQL_SERVER`**
* **`PGSQL_SERVER`**
* **`REDIS_SERVER`**
#### 1.2 Data directories
There are a few pre-configured data directories to make storage persistent across container restarts:
* *`HOST_PATH_TO_WWW_DOCROOTS`*
* *`HOST_PATH_TO_MYSQL_DATADIR`*
* *`HOST_PATH_TO_POSTGRES_DATADIR`*
The values by default point to relative directories inside the devilbox repository. You can however also point them to different locations (relative or absolute)
MySQL and PgSQL data directories will also append their version as a subfolder to the data directories in order to prevent database file corruptions due to different versions and possible incompatabilities between them.
If you have a MySQL database on your host computer with the same version that your docker container is using, you can also interchangeably use the data dir with you host MySQL version and vice-versa.
### 2. The `cfg/` directory
Inside the devilbox root directory you will find a foder called `cfg/`. This will contain subdirectories in the form of `<SERVICE>-<VERSION>`.
Those folders will be mounted into the appropriate location into the respective docker container in order to overwrite service configuration.
Currently only MySQL/MariaDB and PHP/HHVM overrides are supported.
The folder structure looks like this:
```
cfg/
hhvm-latest/
mariadb-10.0/
mariadb-10.1/
mariadb-10.2/
mariadb-10.3/
mariadb-5.5/
mysql-5.5/
mysql-5.6/
mysql-5.7/
mysql-8.0/
php-fpm-5.4/
php-fpm-5.5/
php-fpm-5.6/
php-fpm-7.0/
php-fpm-7.1/
```
Each of the folders will contain an example file in the following format:
```
devilbox-custom.<ext>-example
```
Only files which have the correct file extensions will be read, all others such as `*.<ext>-example` will be ignored.
#### 2.1 Adding PHP options
---
### Hints
**A. Can I not just comment out the service in the `.env` file?**
No, don't do this. This will lead to unexpected behaviour (different versions will be loaded).
The `.env` file allows you to configure the devilbox, but not to start services selectively. At least one version per service must be defined.
**B. I don't want to start all container. How would I do this?**
Head over to the **[Usage](Usage.md)** section to get an in-depth explanation about how to start services selectively.

23
doc/Emails.md Normal file
View File

@ -0,0 +1,23 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
Emails |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Emails
You can send emails from within your PHP projects without having to worry to accidentally sending them out.
All emails to whatever recipients are kept inside by a catch-all functionality from within the `php` container (using postfix).
In order to view the sent emails, use the bundled devilbox intranet and go to the Emails menu. For more information about this see the **[Intranet](Intranet.md)** section.

35
doc/FAQ.md Normal file
View File

@ -0,0 +1,35 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
FAQ
----
## FAQ
**How do I backup my MySQL database?**
1. Use phpMyAdmin
2. Use Adminer
3. use `mysqldump` from your host computer
4. use `mysqldump` from within the php container
**Why are mounted MySQL data directories separated by version?**
This is just a pre-caution. Imagine they would link to the same datadir. You start the devilbox with mysql 5.5, create a database and add some data. Now you decide to switch to mysql 5.7 and restart the devilbox. The newer mysql version will probably upgrade the data leaving it unable to start with older mysql versions.
**Why are mounted PostgreSQL data directories separated by version?**
See: *Why are mounted MySQL data directories separated by version?*
**Why do the user/group permissions of log/ or cfg/ directories show 1000?**

75
doc/Info.md Normal file
View File

@ -0,0 +1,75 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
Info |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Info
### Available containers
It is best to use the hostnames and not to rely on the ip addresses as they might change. In most cases however you can even use `127.0.0.1` or `localhost` (See background section below).
> E.g.: When you want to setup a MySQL database connection use `mysql` or `127.0.0.1` as the hostname.
| Container | Container name | Hostname | IP Address |
|-----------------|-----------------|----------|---------------|
| Apache / Nginx | http | http | 172.16.238.10 |
| PHP / HHVM | php | php | 172.16.238.11 |
| MySQL / MariaDB | mysql | mysql | 172.16.238.12 |
| PostgreSQL | pgsql | pgsql | 172.16.238.13 |
| Redis | redis | redis | 172.16.238.14 |
### Background
#### Background - PHP Container
The `php` container is the center of all container. Everything happens in there.
This is also the reason it does some more magic than actually required.
**Remote ports and remote sockets are made available to the `php` container.**
The PHP container is using [socat](https://linux.die.net/man/1/socat) to
1. forward the remote mysql port `3306` (on the mysql container) to its own `127.0.0.1:3306`
2. forward the remote pgsql port `5432` (on the mysql container) to its own `127.0.0.1:5432`
3. forward the remote redis port `6379` (on the mysql container) to its own `127.0.0.1:6379`
The PHP container is using volumes to
1. mount the remote `mysql.sock` to its own filesystem into a path configured in its `php.ini`
#### Background - Docker Host
The docker host (your computer) does exactly the same as the `php` container.
1. container mysql port `3306` is exposed to the host on port `127.0.0.1:3306`
2. container pgsql port `5432` is exposed to the host on port `127.0.0.1:5432`
3. container redis port `6379` is exposed to the host on port `127.0.0.1:6379`
Also the database sockets from the container are mounted into the host.
#### Background - Benefit of the above
With the PHP container and the docker host (your computer) behaving the same it is possible to write your php applications like this:
```php
<?php
mysql_connect('127.0.0.1', 'user', 'pass');
// or using sockets
mysql_connect('localhost', 'user', 'pass');
```
This setup can then either be served by the docker or by your host computer (if you shutdown docker and start your local lamp stack)
#### Background - Implications
Messing around with socket mounts has caused some problems in the past and it might be subject of change.
In order to stay compatible it is your best choice to use `127.0.0.1` instead of `localhost`.

18
doc/Intranet.md Normal file
View File

@ -0,0 +1,18 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
Intranet |
[FAQ](FAQ.md)
----
## Intranet

56
doc/Logs.md Normal file
View File

@ -0,0 +1,56 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
Logs |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Logs
Log information is available in two forms.
1. Mounted log directories
2. Docker logs
### Mounted log directories
Inside the devilbox directory you will find a folder `log/`.
This itself will contain subdirectories in the form `<service>-<version>` which will then hold all available log files.
**Example:**
```
devilbox/
log/
apache-2.2/
access_log
error_log
localhost-access.log
localhost-error.log
other-error.log
mariadb-10.3/
error.log
query.log
slow.log
php-fpm-7.0/
php-fpm.err
www-access.log
www-error.log
```
### Docker logs
All output that is produced to stdout or stderr by the started service will be available in `docker logs`. In order to view them constantly in a terminal session use:
```shell
docker-compose logs -f
```

106
doc/PHP_Projects.md Normal file
View File

@ -0,0 +1,106 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
PHP Projects |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## PHP Projects
### TL;DR
1. Create folder `${HOST_PATH_TO_MYSQL_DATADIR}/my-project/htdocs
2. Expand docker host `/etc/hosts` with `127.0.0.1 my-project.loc`
3. Browse `http://my-project.loc`
### Adding projects
As an example, we are going to add two projects.
**Prerequisites**
For this case let's assume your www root folder points to `~/www`. This means your projects will reside on your host computer in your home directory under www.
In order to achive this set `HOST_PATH_TO_WWW_DOCROOTS=~/www` in the `.env` file (If this file does not yet exist, copy `env-example` to `.env`).
`.env`:
```
...
HOST_PATH_TO_WWW_DOCROOTS=~/www
...
```
**Desired Projects**
| Project name | Document Root | URL |
|--------------|---------------|-----|
| devilbox | ~/www/devilbox/htdocs | http://devilbox.loc |
| foo.bar | ~/www/foo.bar/htdocs | http://foo.bar.loc |
`htdocs` can either be a folder or a symlink to a folder.
**Project: devilbox**
Setup projects folder and an `index.php` (on your host computer)
```shell
$ mkdir -p ~/www/devilbox/htdocs
$ vim ~/devilbox/htdocs/index.php
```
```php
<?php
echo 'hello world';
?>
```
Adjust your local (host computer) `/etc/hosts` and point `devilbox.loc` to your localhost address `127.0.0.1`
```shell
$ sudo vim /etc/hosts
```
```shell
127.0.0.1 devilbox.loc
```
**Project: foo.bar**
Setup projects folder and use existing github project to serve.
```shell
$ mkdir -p ~/www/foo.bar
$ cd ~/www/foo.bar
# Use an existing github project as your document root
$ git clone https://github.com/<user>/<some-project>
# Symlink the project to htdocs
$ ln -s <some-project> htdocs
$ ls -l
drwxr-xr-x 4 cytopia 1286676289 136 Oct 30 14:24 <some-project>/
lrwxr-xr-x 1 cytopia 1286676289 549 Nov 6 15:13 htdocs -> <some-project>/
```
Adjust your local (host computer) `/etc/hosts` and point `foo.bar.loc` to your localhost address `127.0.0.1`
```shell
$ sudo vim /etc/hosts
```
```shell
127.0.0.1 foo.bar.loc
```

112
doc/README.md
View File

@ -1,82 +1,60 @@
# Documentation # Documentation
## Adding projects [Home](https://github.com/cytopia/devilbox) |
Overview |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
As an example, we are going to add two projects. ----
**Prerequisites** ## Documentation Overview
For this case let's assume your www root folder points to `~/www`. This means your projects will reside on your host computer in your home directory under www. This is a brief overview to get you started as quick as possible. For in-depth documentation use the navigation above.
In order to achive this set `HOST_PATH_TO_WWW_DOCROOTS=~/www` in the `.env` file (If this file does not yet exist, copy `env-example` to `.env`).
`.env`:
```
...
HOST_PATH_TO_WWW_DOCROOTS=~/www
...
```
**Desired Projects**
| Project name | Document Root | URL |
|--------------|---------------|-----|
| devilbox | ~/www/devilbox/htdocs | http://devilbox.loc |
| foo.bar | ~/www/foo.bar/htdocs | http://foo.bar.loc |
`htdocs` can either be a folder or a symlink to a folder.
**Project: devilbox**
Setup projects folder and an `index.php` (on your host computer)
### Install, Configure and Start
```shell ```shell
$ mkdir -p ~/www/devilbox/htdocs # Get the soures
$ vim ~/devilbox/htdocs/index.php $ git clone https://github.com/cytopia/devilbox
$ cd devilbox
# Create and customize the config file
$ cp env-example .env
$ vim .env
# Start your container
$ docker-compose up
``` ```
```php ### Create projects
<?php
echo 'hello world'; The main folder for your projects is defined in `.env` by the variable `HOST_PATH_TO_WWW_DOCROOTS`.
?> Inside this defined folder you will have to create the following directory structure:
```
project1/
htdocs/
project2/
htdocs/
some-random-name/
htdocs -> ./some-dir/ # <-- symlinks are also possible
some-dir/
my-website.com/
htdocs -> /shared/httpd/site.com/ # <-- symlinks are also possible
``` ```
Adjust your local (host computer) `/etc/hosts` and point `devilbox.loc` to your localhost address `127.0.0.1` You will then have to extend `/etc/hosts` with your created foldernames plus the tld suffix:
```shell
$ sudo vim /etc/hosts
``` ```
```shell 127.0.0.1 project1.loc
127.0.0.1 devilbox.loc 127.0.0.1 project2.loc
``` 127.0.0.1 some-random-name.loc
127.0.0.1 my-website.com.loc
**Project: foo.bar**
Setup projects folder and use existing github project to serve.
```shell
$ mkdir -p ~/www/foo.bar
$ cd ~/www/foo.bar
# Use an existing github project as your document root
$ git clone https://github.com/<user>/<some-project>
# Symlink the project to htdocs
$ ln -s <some-project> htdocs
$ ls -l
drwxr-xr-x 4 cytopia 1286676289 136 Oct 30 14:24 <some-project>/
lrwxr-xr-x 1 cytopia 1286676289 549 Nov 6 15:13 htdocs -> <some-project>/
```
Adjust your local (host computer) `/etc/hosts` and point `foo.bar.loc` to your localhost address `127.0.0.1`
```shell
$ sudo vim /etc/hosts
```
```shell
127.0.0.1 foo.bar.loc
``` ```
Contents inside the `htdocs` folder will be server via the configured domain automatically. So in order to access project2's htdoc folder go to `http://project2.loc`

68
doc/Updating.md Normal file
View File

@ -0,0 +1,68 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
[Usage](Usage.md) |
Updating |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Updating
### Tags vs Branches
The devilbox git repository offers two types of setups.
1. Git `tags` for stable release
2. The `master` branch with the latest features
### Git tags
Each new devilbox release is tagged in git and bound to tagged docker images.
Updating only involves to check out the latest tag and make sure to stop and remmove your containers prior starting them up again. Latest docker images will be pulled automatically as their docker tag number will also change between releases.
Additionally you will also have compare `env-example` against your current `.env` file and in case of differences apply them.
```shell
# Update source
$ git fetch --all
$ git checkout <tag>
# Stop and remove your container
$ docker-compose stop
$ docker-compose rm
# Check for config file changes
$ vimdiff .env env-example
```
Currently releases are not that frequent, so you might be better of with the `master` branch.
### Git master branch
The `master` branch does not use tagged docker images, but `latest`. So once you git pull you should also pull the latest docker images.
```shell
# Update source
$ git fetch --all
$ git pull origin master
# Stop and remove your container
$ docker-compose stop
$ docker-compose rm
# Pull latest docker images
$ docker-compose pull
# Check for config file changes
$ vimdiff .env env-example
```

131
doc/Usage.md Normal file
View File

@ -0,0 +1,131 @@
# Documentation
[Home](https://github.com/cytopia/devilbox) |
[Overview](README.md) |
[Configuration](Configuration.md) |
Usage |
[Updating](Updating.md) |
[Info](Info.md) |
[PHP Projects](PHP_Projects.md) |
[Emails](Emails.md) |
[Logs](Logs.md) |
[Intranet](Intranet.md) |
[FAQ](FAQ.md)
----
## Usage
This section is about how to start, stop, view and enter (all or a selection of some) containers. If you want to know how to choose the container type version (e.g. which mysql version or which php version) refer to the **[Configuration](Configuration.md)** section.
**Convention:** The terms *container* and *service* are used interchangeably.
**Assumption:** All `docker-compose` commands must be executed within the devilbox root directory, where the `docker-compose.yml` file resides.
### 1. Start and Stop
#### 1.1 Start all container
```shell
$ docker-compose up
```
This will bring up **all containers** defined in `docker-compose.yml`.
However, you will probably not need all of the defined services and especially on slow machines you only want to start what you really need. This is possible as well.
#### 1.2 Start selected container
In order to only start the services you actually need, you must specify them with the docker-compose command.
**Note:** The `http` and `php` container will automatically be started and must not be explicitly specified. (If not specified, their log output will also not go to stderr/stdout, but instead to docker logs)
```shell
# Only start HTTP and PHP
$ docker-compose up http php
# Start HTTP, PHP and Redis
$ docker-compose up redis
# Start HTTP, PHP and MySQL
$ docker-compose up mysql
# Start HTTP, PHP, PostgreSQL and Memcache
$ docker-compose up pgsql memcache
```
I think you get the idea.
#### 1.3 Start in background
You can also run the docker compose command in the background and close your terminal after startup. To do so simply add the `-d` flag:
```shell
$ docker-compose up -d
```
Or in case of selectively starting
```shell
$ docker-compose up -d mysql
```
#### 1.4 Stop container
1. If you started up docker compose in foreground mode (without `-d`), you can hit `ctrl+c` to gracefull stop or **twice** `ctrl+c` to kill the running containers.<br/>**Note:** Automatically started containers that were not specified (such as `http` or `php`) will have to be stopped manually via `docker-compose down` afterwards.
2. If you started up docker compose in background mode (with `-d`), go back to the devilbox directory (where the `docker-compose.yml` file resides and type `docker-compose down` to gracefully stop or `docker-compose kill` to kill them immediately.
Best pracice would be to start the container in the background (with `-d`) and use `docker compose down` to gracefully stop all of them.
### 2. Container Info
#### 2.1 List running container
Inside the devilbox directory enter the following command to get a list of the started/running container:
```shell
$ docker-compose ps
```
#### 2.2 Show container stdout/stderr output
Services started in background mode (`-d`) or those that were started as dependencies (`http` and `php`) will always only log to docker logs and not to stdout/stderr. In order to view their output use:
```shell
$ docker-compose logs
```
### 3. Enter
#### 3.1 Enter the php container
The `php` container (which might also have hhvm installed, depending on your version choice) is the container you can use to enter if you want to execute commands with the specified php version.
> **Note:** If you also have php installed locally on your host machine (and it is the php version of your choice), there is no need to enter the php container, just execute all the required commands on your project dir.
To enter the php container, type the following:
```shel
$ docker-compose exec --user apache php env TERM=xterm bash -l
```
You can alternatively also just execute the bundled script `enter.sh`
```
$ ./enter.sh
```
#### 3.2 Find your project files
The `php` container mounts your project files (the path of `HOST_PATH_TO_WWW_DOCROOTS` as specified in the `.env` file) to `/shared/httpd`.
So enter the container as described above and once inside the `php` container cd into `/shared/httpd`.
----
### Hints
**A. How do I know the name of the container I can start?**
Refer to the **[Info](Info.md)** section or look it up in the `docker-compose.yml` file.
**B. Can I not just comment out the service in the `.env` file?**
No, don't do this. This will lead to unexpected behaviour (different versions will be loaded).
The `.env` file allows you to configure the devilbox, but not to start services selectively.
**C. Are there any required services that must/will always be started?**
Yes. `http` and `php` will automatically always be started (due to dependencies inside `docker-compose.yml`) if you specify them or not.

BIN
doc/img/devilbox-dash.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 87 KiB