How to launch per cell unit

per-cell vs path-based

There are two kind of URL to specify an address of a cell.

• per-cell
  • the cell url is revealed like this : https://{cell_name}.{unit_fqdn}/
• path-based
  • the cell url is revealed like this : https://{unit_fqdn}/{cell_name}/

path-based security issues

ここにpath-basedの問題点を書く。

Requirements

• Domain

Steps to launch

This tutorial is written on the assumption you use pds.example.com as unit_fqdn.

Prepare DNS

To make your PDS server reachable with pds.example.com, steps below are needed.

Add A records to example.com DNS server.

A record	IP Address
pds	{your PDS server IP}
*.pds	{your PDS server IP}

Generate Certificate

To enable per-cell, it is needed to place some credentials in folders.

Unit Certificate

Self-signed Unit Certificate is needed to show the URL of unit (AP server).

Follow below tutorial. (setting Common Name value to pds.example.com )

• How_to_generate_Self-signed_Unit_Certificate

And then, place files generated onto /path/to/personium-docker/personium/opt/x509

$ ls personium/opt/x509/
unit-self-sign.crt  unit.csr  unit.key

SSL Certificate

SSL Certificate is needed for nginx to use https to serve.

Follow one of tutorials below.

• Create_Server_Certificate_for_Letsencrypt
• Create_Server_Certificate_for_Self-sign

It is strongly recommended to use Letsencrypt if your DNS server can be reached from internet. If you cannot, you can use Self-sign instead of Letsencrypt, but you'll face to Self Cert error in use.

And then, place files generated onto /path/to/personium-docker/nginx

$ ls nginx/
Dockerfile  conf.d  entrypoint.sh  nginx.conf  san.txt  server.crt  server.csr  server.key  server.key.org

Edit Dockerfile

To copy the certificate to container, it is needed to modify Dockerfile.

nginx

Open nginx/Dockerfile and append below lines after row COPY nginx.conf /etc/nginx/nginx.conf.

COPY server.crt /etc/nginx/server.crt
COPY server.key /etc/nginx/server.key

personium

Open personium/Dockerfile and append below lines after row COPY entrypoint.sh ./.

COPY opt/x509/unit-self-sign.crt /opt/x509/unit-self-sign.crt
COPY opt/x509/unit.key /opt/x509/unit.key

Edit files

personium/personium-unit-config.properties

Change io.personium.core.unitCheme value to https and io.personium.core.pathBasedCellUrl.enable value to false

io.personium.core.unitScheme=https
io.personium.core.pathBasedCellUrl.enabled=false

And add below lines.

###### X509 ######
# File path to the X509 root certificate file.
#
# If you do not specify anything, the certificate of Personium's offical
# CA will automatically be trusted.
io.personium.core.x509.root=/opt/x509/unit-self-sign.crt

# File path to the X509 certificate file.
io.personium.core.x509.crt=/opt/x509/unit-self-sign.crt

# File path to the X509 secret key file.
io.personium.core.x509.key=/opt/x509/unit.key

init.sh

Change DOMAIN to your {unit_fqdn} and PATH_BASED_CELL_URL to false.

DOMAIN=pds.example.com
PATH_BASED_CELL_URL=false

And replace http:// urls to https://.

nginx/conf.d/default.conf

Modify like below.

server {
    listen 80;
    server_name *.pds.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen       443 ssl;
    server_name  *.pds.example.com;

    #charset koi8-r;
    #access_log  /var/log/nginx/host.access.log  main;

    ssl         on;
    ssl_certificate     /etc/nginx/server.crt;
    ssl_certificate_key /etc/nginx/server.key;
    ssl_protocols       TLSv1.2;

    location / {
            if ($request_uri ~ [\x00-\x20\x22\x3c\x3e\x5b-\x5e\x60\x7b-\x7d\x7f]) {
                return 400;
            }

            if ($request_uri ~* ([^?]+)\?(.*)) {
              set $personium_path $1;
              rewrite .* /personium-core$personium_path break;
            }
            if ($is_args = "") {
              rewrite .* /personium-core$request_uri break;
            }

            proxy_pass http://personium:8080/;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto https;
            proxy_set_header X-Forwarded-Path $request_uri;
            proxy_set_header Host $host;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_hide_header X-Powered-By;
            proxy_hide_header X-Rack-Cache;
            proxy_hide_header X-Content-Digest;
            proxy_hide_header X-Runtime;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

launch docker

Launch docker container normally.

docker-compose build && docker-compose up -d

If you want to relaunch completely, run command like below.

docker-compose down -v && docker-compose build && docker-compose up -d

Conclusion

This tutorial contains some wrong information, maybe. If you find them, please contact us.