Commit c7866b48 authored by Vincent Delbar's avatar Vincent Delbar
Browse files

ENH: better Docker doc + volume ownership trick

parent d24d73a6
## Docker overview
### Installation
# Docker overview
## Installation
*Windows 10*
```
......@@ -33,9 +33,8 @@ echo \
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io
# https://docs.docker.com/engine/install/linux-postinstall/
# Only if you want to avoid using sudo for each docker command.
# The docker group grants privileges equivalent to the root user.
# Allow user to run docker commands, see https://docs.docker.com/engine/install/linux-postinstall/
# Only if you want to avoid using sudo for each docker command ; docker group grants privileges equivalent to the root user.
sudo groupadd docker
sudo usermod -aG docker $USER
......@@ -43,25 +42,30 @@ sudo usermod -aG docker $USER
docker run hello-world
# Useful commands
docker info # System info
docker images # List local images
docker container ls # List containers
docker ps # Show running containers
docker info # System info
docker images # List local images
docker container ls # List containers
docker ps # Show running containers
# Control state with systemd
#sudo systemctl {status,enable,disable,start,stop} docker
```
### Usage
## Usage
### Pull, create, exec...
N.B. : in previous docker images, default user was **moringa** and every python files were located in `/home/moringa`
In newer images (tag testing, now based on ubuntu 20.04), the default user is now **ubuntu** and you'll find evey python files in `/home/ubuntu/moringa`
```bash
# Pull image
# Pull image (default tag is "latest")
docker pull gitlab-registry.irstea.fr/raffaele.gaetano/moringa
# Simple command in a one-shot container
# Simple command in a one-shot container (anonymous container will not persist)
docker run gitlab-registry.irstea.fr/raffaele.gaetano/moringa otbcli_BandMathX
# Persistent container with volume (here with $HOME, it can be any directory)
docker create --interactive --tty --volume /home/$USER:/home/moringa/data \
# Persistent (named) container with volume, here with home dir, but it can be any directory
# Beware of ownership issues, see the last section of this doc
docker create --interactive --tty --volume /home/$USER:/home/ubuntu/data \
--name moringa gitlab-registry.irstea.fr/raffaele.gaetano/moringa /bin/bash
# Interactive
......@@ -72,13 +76,26 @@ docker start moringa
docker exec moringa ls -alh
docker stop moringa
# Useful container-specific commands
docker inspect moringa
docker logs moringa
docker {pause/unpause} moringa
# Running commands with root user (background container is the easiest way)
docker start moringa
# Example with apt update (you can't use &&, one docker exec is required for each command)
docker exec --user root moringa apt-get update
docker exec --user root moringa apt-get upgrade -y
# Useful container-specific commands, especially for background containers
docker inspect moringa # See full container info dump
docker logs moringa # See command logs and outputs
docker stats moringa # Real time container statistics
docker {pause/unpause} moringa # Pause all container's processes
# Don't forget to kill a background container when you're done
docker stop moringa
# Remove a persistent container
docker rm moringa
```
### How to build
### Build images
```bash
git clone -b develop https://gitlab.irstea.fr/raffaele.gaetano/moringa.git
cd moringa
......@@ -90,12 +107,13 @@ docker build --build-arg OTB_VERSION=7.2 -f docker/base-otb/Dockerfile \
-t gitlab-registry.irstea.fr/raffaele.gaetano/moringa:base-otb-7.2 .
docker push gitlab-registry.irstea.fr/raffaele.gaetano/moringa:base-otb-7.2
# Tag 'base-otb' == default image for next build
# Tag 'base-otb' == default base image for the moringa build
docker tag gitlab-registry.irstea.fr/raffaele.gaetano/moringa:base-otb-7.2 \
gitlab-registry.irstea.fr/raffaele.gaetano/moringa:base-otb
docker push gitlab-registry.irstea.fr/raffaele.gaetano/moringa:base-otb
# MORINGA build from the 'base-otb' image
# MORINGA build from the default 'base-otb' image
# You don't need to rebuild OTB if you just want to update moringa files using current branch / local commits
docker build -f docker/moringa/Dockerfile -t gitlab-registry.irstea.fr/raffaele.gaetano/moringa .
docker push gitlab-registry.irstea.fr/raffaele.gaetano/moringa:latest
......@@ -104,3 +122,38 @@ docker build -f docker/moringa/Dockerfile \
--build-arg BASE_IMG=gitlab-registry.irstea.fr/raffaele.gaetano/moringa:base-otb-dev \
-t gitlab-registry.irstea.fr/raffaele.gaetano/moringa .
```
### Fix volume ownership issue (required if host's UID > 1000)
When mounting a volume, you may experience errors while trying to write files from within the container.
Since the default user (ubuntu) is UID 1000, you won't be able to write files into your volume which is mounted with the same UID than your linux host user (may be UID 1001 or more).
In order to address this, you need to edit the container's user UID and GID to match the right numerical value.
This will only persist in a named container, it is required every time you're creating a new one.
```bash
# Create a named container (here with your HOME as volume)
docker create --interactive --tty --volume /home/$USER:/home/ubuntu/data \
--name moringa gitlab-registry.irstea.fr/raffaele.gaetano/moringa /bin/bash
# Start a background container process (in order to exec root commands, because default user isn't sudoer)
docker start moringa
# Exec required commands with user root (here with host's user ID, or you'll need to replace $UID and $GID with desired values)
docker exec --user root moringa usermod ubuntu -u $UID
docker exec --user root moringa groupmod ubuntu -g $GID
# Force reset ownership with updated UID and GID.
# Make sure to double check what you're doing since recursive chown will apply to your volume in /home/ubuntu/data)
docker exec --user root moringa chown -R ubuntu:ubuntu /home/ubuntu
# Stop the background container and start a new interactive shell
docker stop moringa
docker start -i moringa
```
```bash
# Check if ownership is as exepected
id
ls -Alh /home/ubuntu
ls -Alh /home/ubuntu/data
# Test writing a file
touch /home/ubuntu/data/test.txt
```
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment