Setup

Deployment

This document aims to help you deploying, starting and managing your IdentityHub instance.

# Execute locally

Copy executable to the desired location, copy the config folder next to it.

Rename the default.toml inside the config folder to local.toml. Configure your IdentityHub as seen here.

In certain cases (i.e. if your ldap server is using a self signed certificate), it is necessary to make them available in the underlying node process.

To do so, gather all necessary certificates in one file (i.e. ca-bundle.pem in config folder). Start IdentityHub with NODE_EXTRA_CA_CERTS=<path/to/ca-bundle.pem>

.
└─ srv
    └─ identity-hub
              ├─ config
              │    └─ ca-bundle.pem
              │    └─ local.toml
              └─ identity-hub (executable)

After this setup just execute the 'identity-hub' file.

cd /srv/identity-hub
NODE_EXTRA_CA_CERTS=./config/ca-bundle.pem ./identity-hub

The terminal output should look like this (depending on your configured host and port and log settings):

[16:37:41.860] INFO: loaded configuration
    server: {
      "host": "0.0.0.0",
    ... (truncated log of the read configuration)

[16:37:42.511] INFO: 2.515 server.bootstrap
  ├─ 0.203 ldap.find → ok
  │  └─ 0.157 ldap.pool.acquire
  │     ├─ 0.156 ldap.connect
  │     ├─ 0.160 ldap.connect
  │     ├─ 0.165 ldap.connect
  │     ├─ 0.198 ldap.connect
  │     ├─ 0.549 ldap.connect
  │     ├─ 0.550 ldap.connect
  │     ├─ 0.550 ldap.connect
  │     ├─ 0.550 ldap.connect
  │     ├─ 0.549 ldap.connect
  │     └─ 0.549 ldap.connect
  ├─ 0.024 server.listen › 0.0.0.0:4000
  ├─ 0.101 ldap.pool.start
  └─ 0.042 i18n.init › config/locales/{{lng}}/{{ns}}.yaml: de,en
    trace_id: "4025c25dfeefcdee9ea464400895ded1"

Now the IdentityHub accepts graphql requests under http://0.0.0.0:4000/-/graphql. To access a graphql-playground, configure the IdentityHub to expose it.

# Execute as a service with seperate logfile

Create user and group on SuSE

groupadd identity-hub

useradd --system -c 'identity-hub' -d /srv/identity-hub -m identity-hub -s /bin/sh -g identity-hub

Lock the user account

passwd -l identity-hub

Switch to user (optional)

su - identity-hub

Create a /etc/systemd/system/identity-hub.service file on the server (If another identity-hub.service exists under /usr/lib/systemd/system this will override the one under /etc/systemd/system and therefore the changes won't take effect!)

[Unit]
Description=IdentityHub

[Service]
WorkingDirectory=/srv/identity-hub

Type=simple

User=identity-hub
Group=identity-hub

PermissionsStartOnly=true

# make sure the log file exists and is writable
ExecStartPre=/bin/sh -c "[ -e /var/log/identity-hub.log ] || touch /var/log/identity-hub.log"
ExecStartPre=/bin/sh -c "chmod 640 /var/log/identity-hub.log"
ExecStartPre=/bin/sh -c "chown identity-hub:identity-hub /var/log/identity-hub.log"

ExecStart=/bin/sh -c "NODE_EXTRA_CA_CERTS=config/ca-bundle.pem ./identity-hub 2>&1 >> /var/log/identity-hub.log"

[Install]
WantedBy=multi-user.target

Optionally create a logrotate.conf to /etc/logrotate.d/identity-hub and, if desired, adapt it to your needs.

Example logrotate config:

/var/log/identity-hub.log {
  su root root
  compress
  delaycompress
  weekly
  maxsize 5M
  rotate 7
  notifempty
  missingok
  copytruncate
}

Copy IdentityHub Binary to /srv/identity-hub

scp </path/to/identity-hub> root@<server-ip>:/srv/identity-hub/identity-hub

Copy the config folder next to the executable and rename the default.toml to local.toml. Configure everything as seen here. Or use the configuration-manager to create a configuration file from scratch.

Gather all necessary certificates in one file (i.e. ca-bundle.pem in config folder). Start IdentityHub with NODE_EXTRA_CA_CERTS=<path/to/ca-bundle.pem>. Or you can adapt the identity-hub.service file accordingly (Environment=NODE_EXTRA_CA_CERTS=<path/to/ca-bundle.pem>)

.
└─ srv
    └─ identity-hub
              ├─ config
              │    └─ local.toml
              └─ identity-hub (executable)

Enable and start Service

systemctl enable identity-hub

systemctl start identity-hub

Check service status

systemctl status identity-hub

Stop service

systemctl stop identity-hub