Personium Unit - Docker Container

Personium architecture has three-layered objects. We highly recommend reading the architecture to conceptually understand various component namings and responsibilities.

This repository builds a container image and runs a Personium Unit container with Docker. A Personium Unit can be managed by a Unit Manager. If you would like to develop or test a Personium Unit without building one, please reach out to us in Slack community so that we can create demo accounts (Cells) for you.

Requirements

The followings must be installed and configured in advance to build and run Personium Unit offered from this repository.

• Docker
• Docker Compose

Windows 10 User

Special requirements if you want to run Docker in Windows 10. Follow the official instructions from Microsoft to install WSL 2.

Useful tutorials to go through before you start installing anything:

• A Linux Dev Environment on Windows with WSL 2, Docker Desktop and More
• Using Docker in Windows for WSL2

Setup

Please refer to the Overview of docker-compose CLI for details.

Step 1. Build your services

Execute the following commands inside the cloned repository in your local environment. Execute the commands again after changing any docker related files.

# docker-compose build
# docker-compose up -d

"-d" option allows the containers to be run in the background

Step 2. Initialize your Personium Unit

After the "docker-compose up -d" command finished building and starting the services, execute following command on your host machine to create an admin Cell so that you can manage the Personium Unit.

$ ./init.sh

After execution, a file named unitadmin_account will be created. The file contains login information for the admin Cell.

To use management tool, see here.

Default configurations are as follows.

• unitScheme=http
• pathBasedCellUrl.enabled=true

So a cell URL is http://localhost/alice/, not https://alice.localhost/.

Windows 10 User

Extra softwares are required to execute the above command successfully in Windows 10. However, you can execute the following commands directly in Windows Terminal or Command Prompt.

1. Docker command to copy local file to container's folder.

    personium-docker> docker cp ./init.sh personium-docker_nginx_1:/root/init.sh  
   

2. Docker command to start a bash prompt that connects to the container.

    personium-docker> docker exec -it personium-docker_nginx_1 /bin/bash  
   

3. Execute the following commands to access "init.sh" and start the shell script.

    root@7aeb90f09ec5:/# cd /root    
    root@7aeb90f09ec5:~# ls -l    
    total 8    
    -rwxr-xr-x 1 root root 4583 Jul 20 09:36 init.sh    
    root@7aeb90f09ec5:~# bash init.sh    
   

4. Execute the follwoing commands to verify the contents of "unitadmin_account".

    root@7aeb90f09ec5:~# ls -l  
    total 12  
    -rwxr-xr-x 1 root root 4583 Jul 20 09:36 init.sh  
    -rw-r--r-- 1 root root  111 Jul 23 15:19 unitadmin_account  
    root@7aeb90f09ec5:~# cat unitadmin_account  
   

Step 3. Create Cell

To create cell, see Cell creation tutorial.

Or execute the following script which does the equivalent of doing the above steps.

$ ./create_cell.sh <cell_name>

Before executing create_cell.sh, jq command installation is required.

In the created cell, the following account with root priviledge is also created.

• username: me
• password: changeme

Start/Stop your services

The following commands are useful for starting or stopping the built servcies.

# docker-compose start
# docker-compose stop

Clean up and rebuild environment

Execute the following docker commands to clean up your local environment for a fresh start.

Step 1. Check current status

# docker-compose ps
# docker-compose ps -a

Step 2. Remove containers

# docker-compose rm -v -s
# docker-compose ps
# docker-compose ps -a

Step 3. Remove volume

# docker volume ls
DRIVER              VOLUME NAME
local               personium-docker_esdata

# docker volume rm personium-docker_esdata

Step 4. Rebuild without cache

# docker-compose build --no-cache
# docker-compose up -d