# Introduction

Tevun is just a set of scripts made to run docker-compose projects in remote servers. It combines docker, docker-compose and git to automate tasks in your server = )

![](/files/-LhcPmiKOfIUo55WFIat)

[Tevun](https://github.com/tevun/server) is a set of scripts intended to make life easier for developers and sysadmins in general.

It combines docker, docker-compose and git to automate tasks such as uploading containers, configuring reverse proxy, configuring SSL, and more.

After setting up Tevun on your server you can upload an environment that applies your development docker-compose and configures a virtual host for your LetsEncrypt SSL-enabled domain quickly and simply.

Each created project generates a remote git that is already pre-configured to publish the application to the destination directory.

That way we can configure the scripts to publish our changes in our stage or production environments.

{% hint style="info" %}
We recommend this project to people with some experience with terminal, git, linux, docker and docker-compose. If you already uses docker-compose in your development environment Tevun can make sense to you ; )
{% endhint %}

### Follow

\- [Telegram](https://t.me/tevun)\
\- [Twitter](https://twitter.com/tevunapp)\
\- [Site](https://tevun.com)


# Installation

Simple tutorial to make your server run with Tevun

## 1. Requirements

Verify that your server has the following requirements:

* Bash (echo ${BASH\_VERSION}): +4.x.x
* Git (git --version): git version +2.10.x  
* Docker (docker -v): Docker version +18.0x.x-ce
* Docker Compose (docker-compose -v): docker-compose version +1.2x.x

## 2. Download and install

Access your server using ssh

```
$ ssh root@<server>
```

Then create the installation dir, clone repository and create the symlink to use command `tevun` in terminal (copy and paste the four lines in the terminal, read the instructions - *always read what you execute* - and then press enter)

```
mkdir -p /usr/share/tevun && \
git clone https://github.com/tevun/server.git /usr/share/tevun && \
cd /usr/share/tevun && \
ln -s $(pwd)/tevun.sh /usr/bin/tevun
```

Now we can perform `tevun` in terminal.

![Output command "tevun" when we do not pass parameters](/files/-LfXdiwsVaFfF5JCaMPp)

## 3. Setting up Tevun

Let's configure Tevun on your server. First, let's check the user settings and permissions, and then let's configure Tevun.

## 3.1. Users and permissions

{% hint style="info" %}
if you already have an user with the necessary permissions to run your containers or this is not relevant to your scenario you can just disregard this topic.
{% endhint %}

It is important that you avoid using your root user via SSH. It is recommended that you create an user that is limited in order to be able to access your server via SSH. Since we are dealing with docker, we need to have a local user with the same UID that the images will use. Usually this **UID** is the *1000*. To facilitate this operation you can **optionally** use the command below, where `<name>` is the name you want to assign to the new user.

```
sudo tevun user <name>
```

{% hint style="warning" %}
This command will also add the new user to the docker group and sudoers group
{% endhint %}

## 3.2. Access policy via SSH

You can use a single Tevun command to configure a less privileged user to access SSH and disable root access by using the command below.

{% hint style="danger" %}
Just use it if you know what it's doing!
{% endhint %}

```
sudo tevun ssh <name>
```

## 3.3. Tevun setup

To perform the setup use the following command in the terminal, replacing \<user> with the name of the user that will be used to manipulate the containers.

```
sudo tevun setup <user>
```

![](/files/-LfXJ-5R8NWwqphBRIUk)

The setup command will ask some stuffs.

* Host: used to generate the remote paths
* HTTP Port: sets the HTTP port for the tevun container outside reverse proxy
* HTTPS port: HTTPS port used outside proxy
* SSH port: used to generate the remote paths
* User ID to be used in project: define the owner of projects

After perform this command you can access the your server in port 1080 (the default value for HTTP port) to see if it works.

![Accessing outside reverse proxy using a custom port](/files/-LfXJdBQDfUoRBfh28Ui)

![Access the default Tevun page through the reverse proxy](/files/-LfXh_wlI0A0pAHj_V8f)

## 3.4. What happened in my server?

Setup command created 3 containers to make all stuffs running:

* [nginx-proxy](https://github.com/jwilder/nginx-proxy): a nginx instance to make the reverse proxy and allow we up various containers to the same port
* [nginx-letsencrypt](https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion): a listener to docker socket that run [**LetsEncrypt**](https://letsencrypt.org) bot to VIRTUAL\_HOST property of containers environment
* [tevun](https://github.com/tevun/server/blob/master/.docker/tevun/Dockerfile): nginx server configured to run CGI and communicate with docker of host

If you are here and is all right you can start creating projects your server! Go to [Getting Started](/getting-started) to use the resources.

Check [How it works](/how-it-works) session to understand how the [Tevun Initiative](https://tevun.com).

> In case you got issues in this process keep in touch. You can open issues in our [repo](https://github.com/tevun/server) or call in [telegram](https://t.me/tevun) = )


# Getting started

After Tevun is installed and configured in your server we can go ahead

## Host operations

These operations are performed on the server. They allow you to configure the projects and repositories that will be used by the team.

### Create a new project

```
tevun create <project> <template>
```

This command will add a new project in projects directory. Where `<project>` is the name of project and `<template>` can be **php** or **html**. We can add other templates too. The main idea is to have skeletons to most common structures used.

```
tevun create site.com html
```

In this example Tevun will create `site.com` project, initialize a git remote repository, configure `post-receive`, generate a `docker-compose.yml` and show the git remote URL in terminal.

![](/files/-LcWIUC-i7yQTF7wd-xw)

### **Destroy a project**

```
tevun destroy <project>
```

The command destroy will stop your docker-compose project and erase the project directory.

{% hint style="danger" %}
The command will not erase the docker volumes, but is important to be careful with this instruction.
{% endhint %}

### Register users

Once the projects have been created we can make a local clone of them, but for that we need an user with access permission. To register users in Tevun use the command below:

```
tevun register <user>
```

This is a short hand to http basic auth and the file with permissions is in file `/etc/nginx/.users` of *tevun* container.

![](/files/-LcWIsewlmhtThVEUDR4)

## Using in a workstation

After having a project created on the server we can use git to publish it and even use the sample project as the basis for working on it.

### Configure in a new project

Clone the host created in your Tevun server:

```
git clone https://<user>@<host>:<port>/<project>/repo <dir>
```

Fetch the setup branch, get setup branch from remote and merge setup branch to your local branch:

```
git fetch deploy +refs/heads/setup:refs/remotes/deploy/setup && \
git branch --track setup refs/remotes/deploy/setup && \
git merge --no-ff deploy/setup --allow-unrelated-histories
```

### **Configure in an existing project**

If you already has a project can make something like the previous section. We can get the branch setup of project repository to get the files to configure our project to run in Tevun.

Add the remote to your local repository:

```
git remote add deploy https://<user>@<host>:<port>/<project>/repo
```

Fetch the setup branch, get setup branch from remote and merge setup branch to your local branch:

```
git fetch deploy +refs/heads/setup:refs/remotes/deploy/setup && \
git branch --track setup refs/remotes/deploy/setup && \
git merge --no-ff deploy/setup --allow-unrelated-histories
```

### Git issues

If a ***host*** with https support is not being used, we can use a configuration for `git` to be more flexible with respect to the certificate

```
git config http.sslVerify false
```

### Using a full qualified name with git

The Tevun configuration will not configure a dedicated virtual host for the tevun container, but it is quite easy to do so. Go to the Tevun installation folder and open the file `docker-compose.yml`. Set the tevun container to leave the `environment` property as the image below

![](/files/-LfXantMrMv3aU6C3SNp)

{% code title="docker-compose.yml" %}

```yaml
version: '3.7'
#  ...
services:
#  ...
 tevun:
#  ...
  environment:
    - VIRTUAL_HOST=tevun.mydomain.com
    - LETSENCRYPT_EMAIL=it@mydomain.com
    - LETSENCRYPT_HOST=tevun.mydomain.com
```

{% endcode %}

After update `docker-compose.yml` restart the project

```
docker-compose down && docker-compose up -d
```


# How it works

to understand how Tevun works it is necessary to understand what pieces it joins and how they fit together.

## 1. Glossary

### 1.1. Docker

Docker is a computer program that performs operating-system-level virtualization. With `docker` we can run services in the same kernel as containers.

### 1.2. Docker Compose

Compose is a tool for defining and running multi-container Docker applications. Using `docker-compose` it is possible describe the services in an YAML file and Compose will manage the containers.

### 1.3. Git

Git is a distributed version-control system for tracking changes in source code during software development. It will be used to handle the base code and make the new changes available.

### 1.4. Git Hooks

Git hooks are scripts that Git executes before or after events such as: commit, push, and receive. Git hooks are a built-in feature - no need to download anything. Git hooks are run locally. In Tevun we configure the post receive-hook when you create a new project to receive push and deploy the code, but git has others hooks that can be useful to other routines.

## 2. Tevun new project

A new project in Tevun create a docker-compose project sample that need to be extended without lose some principles.

![](/files/-LcXUMuar5ABVJlLFaFh)

## 3. Tevun project logistic

When we create a Tevun project is created behind the new project a small logistic to handle with the code base.

![](/files/-LcXRA6_ItllfyP5sXJW)


# API

Describes the resources available in Tevun

## setup

```
# tevun setup [<user>]
```

{% hint style="warning" %}
Requires root privilegies
{% endhint %}

## create

```
$ tevun create <project> <template>
```

## destroy

```
$ tevun destroy <project>
```

{% hint style="success" %}
Requires user confirmation
{% endhint %}


# Dockerize

Bash like abstraction of local services in docker

When assuming the use of container in our workflow we come to face some challenges. Soon we realize that it is complicated to have a complete environment without installing any tool on the host.

[Tevun's Dockerize](https://github.com/tevun/dockerize) initiative seeks to deliver a comfortable workflow for those who use Docker in their day-to-day lives.

Using it you will abstract all the services you use to develop to run with docker.

## How to configure

{% hint style="danger" %}
Read the steps before you run them to understand what is being done. We will modify your bash environment and we don't want cause problems to you = )
{% endhint %}

### Getting started

To use *`dockerize`* you can clone or download de zip of project from Github.

#### Create a clone

Create with your terminal an easy-to-find folder

```bash
mkdir -p ~/.config/tevun
```

Make a local project clone

```bash
git clone git@github.com:tevun/dockerize.git ~/.config/tevun/dockerize
```

OR

#### Download

Download the zip of this project

```bash
wget -O ~/.config/tevun/dockerize.zip https://codeload.github.com/tevun/dockerize/zip/master
```

Then unzip the contents of the zip

```bash
unzip dockerize.zip && mv dockerize-master dockerize
```

## Configuration

To use *`dockerize`* you need add the [bashrc](https://github.com/tevun/dockerize/blob/master/.bashrc) script to your terminal environment.

{% code title="\~/.bashrc" %}

```bash
...
source ~/.config/tevun/dockerize/.bashrc # or your custom path
...
```

{% endcode %}

If you are using the project for the first time you can use our convenient configuration script to add local documents to your terminal environment.

To do this, run the configuration script

```bash
bash ~/.config/tevun/dockerize/configure.sh # or your custom path
```

### How to use `Dockerize`

After add the script to terminal will be created a command engine to toggle service commands to run on "[global images](https://github.com/tevun/dockerize/tree/master/dockerize/environment)" and/or containers relative to the project of the folder it is in.

We currently have the following configured services:

* artisan
* composer
* node
* npm
* php
* phpunit
* quasar
* vue
* yarn
* react

In other words, you can simply execute:

```bash
php -v
```

To perform the service php in your docker host.

### Smart behavior

*`Dockerize`* tries to detect which container should be run for each service. When you are in a folder that does not have a container associated with it, your output will be global.

![](/files/-LcXdrDJoXgSeShk4vpj)

When the current directory is associated with one container the output will be different.

![](/files/-LcXdhwosRadS2_vQf2O)

### Detection strategies

* global suffix: *`Dockerize`* will first attempt to find a container that has the folder name and suffix associated with the service. You can check the service suffix in the property `T_DOCKERIZE_SERVICE` of file `dockerize/environment/variables.ini.sample`. If your project folder is `foo` and `T_DOCKERIZE_SERVICE` is `app` the name of your service must be `foo-app` to this detection match.&#x20;
* service suffix: The second try is check if there is a container with the folder name followed by an hyphen and the name of service. If your project folder is `acme` and you create a service with name `acme-node` you can perform the command `node` and *`dockerize`* will use this container.
* file `.dockerize`: You create a file called `.dockerize` in your project folder and describe the name of containers of services.

## Customizing

You can customize the main project settings. Go to the environment folder and evaluate the parameters that are defined there.

```bash
cd ~/.config/tevun/dockerize/environment
```

## Common Problems

* **Address already in use:**&#x20;
  * **message**: docker: Error response from daemon: driver failed programming external connectivity on endpoint \* (): Error starting userland proxy: listen tcp 0.0.0.0:: bind: address already in use.
  * **solution**: use the guidelines in the Customizing section and configure the ports in the images.ini file according to your port usage.


# FAQ

## What is reverse proxy and why I need it?

Reverse is proxy is a strategy of redirect the inbound requests to specific resources. Using docker you will need use the same host port to many purposes. In this time you will up a reverse proxy to redirect the domain requests to a specific container network.

## Why Tevun is better then others options?

Tevun is not better then [Traefik](https://traefik.io), [CapRover](https://caprover.com), [Devilbox](http://devilbox.org) or another mature tool. In fact you achieve the same result with several other tools. We continue to maintain Tevun because it is the way we believe it to be simpler for most of the scenarios we deal with. If looks useful to you go on, else let it go.