Skip to main content

SAMO Ready Debian OS

This guide describes the preparation steps for operating system and programs that need to be completed before any SAMO installation.

info

This guide focuses on Debian-based Linux (e.g., Ubuntu). Other distributions may differ. For additional information, refer to the official Docker installation guides.

tip

Lines starting with $ are shell commands.

Prepare Operating System​

Some tips for tools and steps for OS.

The operating system should be up to date not because of bug fixes and improvements but also because of the security. This step is not necessary but highly recommended.

$ apt-get update && apt-get upgrade​

I also recommend to restart the system after update but it also should not be necessary step.

$ reboot

Install essential tools- Some tools are not part of OS by default but they are good for debugging and investigating problems.​

$ apt-get install net-tools apt-transport-https ca-certificates curl gnupg2 software-properties-common zip unzip

Check ​proxy settings and connectivity​

In case the server is behind proxy server we need to ensure that it is correctly configured.

Check whether www.google.com is accessible with one of these commands:

If the command are not working there is probably http_proxy is not properly set. In order to set the proxy put the export commands to the /etc/environment file (for CentOS/Oracle/RHEL):

  • ​​export http_proxy=PROXY_URL_WITH_PORT
  • ​​export HTTP_PROXY=PROXY_URL_WITH_PORT
  • ​​export https_proxy=PROXY_URL_WITH_PORT
  • ​​export HTTPS_PROXY=PROXY_URL_WITH_PORT

Proxy address and port can usually be found like this:

  • ​grep -rnw '/etc' -e "proxy"​

Then you can test the connection again.

This is not enough to provide proxy setup upon startup. You have to add these properties to the server environment. Add them to the /etc/environment file and reboot. You can check the properties after system reboot.

Check ​IP forwarding​

The IPv4 forarwarding is needed for Docker to work correctly.

  1. Check if enabled:
  • cat /proc/sys/net/ipv4/ip_forward​
  1. If not
  • uncomment line:
    • net.ipv4.ip_forward = 1
  • in file:
    • ​/etc/sysctl.conf​​​​
  • and restart procps service:
    • /etc/init.d/procps.sh restart​

Tip: Shell Aliases​

It is convenient to set up some shortcuts for working with Docker on the command line.

We use these aliases:

alias dcu='docker compose up -d'
alias dcd='docker compose down'
alias dcp='docker compose pull'
alias dcinstall='dcp && dcd && dcu'

alias dlog='docker logs -f'
alias dlogt='docker logs -f --tail 1000'

alias dstats='docker stats $(docker ps --format={{.Names}})'

alias dps='docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | sed -r "s/0.0.0.0://g" | sed -r "s/\/tcp//g" | sed -r "s/://g"'
alias dpsa='docker ps -a --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | sed -r "s/0.0.0.0://g" | sed -r "s/\/tcp//g" | sed -r "s/://g"'

They are stored in the /etc/bashrc file which is loaded upon user login.

Function for "docker exec" should be stored in ~/.bashrc. After saving function in this file load new settings by source ~/.bashrc.

dex() {
  if [ -z "$1" ]; then
    echo "Použití: dex <container>"
    return 1
  fi
  docker exec -it "$1" bash
}

Install Docker (Required)​

Docker is our choice for containers. So far the only supported option for SAMO. It is also possible to install without Docker but the process is cumbersome and not bulletproof with a lot of dirty hand work.

Install packages to allow apt to use a repository over HTTPS​

$ apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

Add Docker’s official GPG key​

$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

Set up the stable repository for Docker​

$ add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

Instal docker itself​

Install the latest version of Docker CE and containerd

$ apt-get install docker-ce docker-ce-cli containerd.io

The docker uses IP address range (by default 172.17.0.1 with mask 255.255.0.0) which might collide with infrastructure making it impossible to connect to the host using SSH. After docker installation and before reboot it is important to check this possible collision. Run $ ifconfig and look if your eth0 collides with the docker0 interface. (Collide means that the IP are overlaping).

In case that the eth0 uses 172... IP addresses you should change docker base IP address. Create file (if not exist) /etc/docker/daemon.json and paste this snippet:

{
  "bip": "10.9.0.1/24",

  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "10"
  }
}

This file contains all configuration for Docker daemon. We also added log settings which is helpful for long-running containers where log files can get huge.

warning

After making changes to /etc/docker/daemon.json, you must restart Docker service with systemctl restart docker and verify that the IP address changed using ifconfig.

Docker Service​

sudo systemctl start docker
sudo systemctl enable docker

Verify Docker is running​

$ ​docker version

Docker and proxy settings​

The most robust proxy settings which survives docker updates is with systemd settings. It is about creating simple files wich add service Environment variables to the Docker service.

  1. Create systemd configuration folder if it does not exist:
sudo mkdir -p /etc/systemd/system/docker.service.d
  1. Create /etc/systemd/system/docker.service.d/http-proxy.conf file and paste (edit the NO_PROXY according to your infrastructure):
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:80/"
Environment="NO_PROXY=localhost,127.0.0.1,gitlab,*.company.com,*.company.local,.company.com,.company.local"
  1. Create /etc/systemd/system/docker.service.d/https-proxy.conf file and paste:
[Service]
Environment="HTTPS_PROXY=https://proxy.example.com:80/"
  1. Reload service daemon and restart Docker service:
sudo systemctl daemon-reload
sudo systemctl restart docker

For more information see official guide: Control Docker with systemd.

Enable the Docker service (optional)​

In order to automatically start the Docker service upon server startup you have to enable the service.

$ ​systemctl enable docker

tip

Reboot the system after enabling Docker service and check the system upon startup.

Install Docker Compose (Required)​

Docker Compose provides service orchestration which we use in our SAMO distribution. Therefore it is important to install this utility as well as Docker itself.

The easiest way to install Docker Compose is to download the binary and create a link:

sudo curl -L https://github.com/docker/compose/releases/download/1.23.2/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
info

Updating Docker Compose is done the same way as installation. Just use a higher version number in the command above. See the Docker Compose release page to find the latest version.

Troubleshooting​

Some tips we found useful when using Docker.

Trust Self-Signed Certificates​

If you need to use a self-signed certificate which is not considered trustworthy, you can tell Docker to trust it for a certain hostname:

  1. Get certificate and name it: ca.crt
  2. Copy it to: 
    /etc/docker/cert.d/HOSTNAME:PORT/ca.crt
    /etc/pki/ca-trust/source/anchors/ca.crt
  3. Run: update-ca-trust
  4. Restart Docker: sudo systemctl restart docker