roof/pic
1
0
Fork 0
Code Issues Pull Requests Actions Wiki Activity
Page: Admin – Install and First Run
Pages
ADR – 001 Store Images Are Signed and Verified by Cells ADR – 002 Named Connection Instances for Connectivity ADR – 003 All Optional Functionality Ships as Store Services Admin – Back Up and Restore Admin – Configure Connectivity Admin – Configure Domains and TLS Admin – Install and First Run Admin – Logging and Audit Admin – Manage Peers Admin – Manage Services Admin – Monitor and Troubleshoot Admin – Overview Archive – ADR 004 The Wiki Is the Single Documentation Source Archive – User Guide Dev – API Reference Dev – Architecture Dev – Build a Store Service Dev – Install Internals Dev – Overview Dev – Service Manifest Reference Dev – Testing Home Meta – Glossary Meta – Template ADR Meta – Template Runbook User – Connect to the VPN User – FAQ User – Start Here User – Troubleshooting User – Use Your Services
Clone
Admin – Install and First Run
Dmitrii Iurco edited this page 2026-06-11 15:39:28 -04:00
Table of Contents

Status: Active | Owner: @roof | Applies to: main (2026-06) | Updated: 2026-06-11

Admin – Install and First Run

Installation

Option A — one-line installer (recommended)

# Run on: your Linux server, as a user with sudo access
curl -fsSL https://install.pic.ngo | sudo bash

Before running any script as root, review it first:

# Run on: your Linux server
curl -fsSL https://install.pic.ngo | less

The installer accepts two flags:

  • --debug — print verbose output to the terminal instead of only to the log file
  • --force — bypass the idempotency check (re-run on an already-installed host)

The install log is always written to /var/log/pic-install.log. If anything fails without --debug, check that file.

The installer runs 7 steps:

  1. Detects your OS and package manager (apt / dnf / apk)
  2. Installs Docker, git, make, and host chrony (NTP)
  3. Creates a pic system user and adds it to the docker group
  4. Clones the repository to /opt/pic
  5. Runs make install — generates keys, config, and a systemd unit; prints the admin password once
  6. Runs make start-core to bring up the six core containers
  7. Enables the pic systemd unit and waits for the API health check

When the installer finishes, it prints a URL:

Open your browser: http://<host-ip>:8081/setup

Option B — manual install

Use this if you want to control the install path or if Docker is already installed:

# Run on: your Linux server, as root or with sudo
git clone https://git.pic.ngo/roof/pic.git pic
cd pic
sudo make install
make start-core

Install host chrony before running make install if you plan to use pic.ngo domain mode:

# Debian / Ubuntu
sudo apt-get install -y chrony && sudo systemctl enable --now chrony

# Fedora / RHEL
sudo dnf install -y chrony && sudo systemctl enable --now chronyd

# Alpine
sudo apk add chrony && sudo rc-update add chronyd default && sudo service chronyd start

Then open http://<host-ip>:8081/setup.

The first-run wizard

The wizard appears automatically on first start. All API requests redirect to /setup (HTTP 428) until the wizard is complete.

The wizard collects:

  • Cell name — used for hostnames and the DDNS subdomain. Must start with a lowercase letter, be 2–31 characters, and contain only lowercase letters, digits, and hyphens. Example: myhome.
  • Domain mode — see Admin – Configure Domains and TLS for details.
  • Timezone — your local timezone, used for log timestamps.
  • Services to install — optional services (email, calendar, files) to start installing in the background after setup completes. You can install them later from the Services page instead.
  • Admin password — minimum 12 characters; must contain at least one uppercase letter, one lowercase letter, and one digit.

Click Complete Setup. The wizard:

  1. Creates the admin account in data/auth_users.json
  2. Writes cell identity to config/api/cell_config.json
  3. Generates the initial Caddyfile and Corefile
  4. If domain mode is pic_ngo, registers <cell-name>.pic.ngo with the DDNS service
  5. Starts any selected services in background threads

You are redirected to /login. Log in with username admin and the password you set.

Cell identity

The three core identity values are:

Value Where set Example
Cell name Wizard / Settings myhome
Domain mode Wizard / Settings pic_ngo
Timezone Wizard / Settings Europe/Berlin

These are stored in config/api/cell_config.json under the _identity key. Do not edit this file directly — use the Settings page in the UI or the API.

The cell's WireGuard VPN uses the subnet 10.0.0.0/24 (the server address is 10.0.0.1/24). This is configured in api/wireguard_manager.py and is not currently exposed in the wizard UI.

After the wizard

Resetting the admin password

If you forget the admin password:

# Run on: the cell server host, from /opt/pic
make show-admin-password    # print the current password
make reset-admin-password   # generate and set a new random password

Updating PIC

# Run on: the cell server host, from /opt/pic
make update    # git pull + rebuild all images + restart

Uninstalling

# Run on: the cell server host, from /opt/pic
make uninstall

This stops all containers and removes the systemd unit. It then asks whether to also delete config/ and data/.

⚠️ Warning: Answering yes to the data deletion prompt performs a full wipe — all configuration, keys, peer data, and service data are deleted and cannot be recovered without a backup.

Internals: see Dev – Install Internals

Personal Internet Cell

Home

New here?

User – Start Here User – FAQ

Users

User – Connect to the VPN User – Use Your Services User – Troubleshooting

Admins

Admin – Overview Admin – Install and First Run Admin – Configure Domains and TLS Admin – Manage Services Admin – Configure Connectivity Admin – Manage Peers Admin – Back Up and Restore Admin – Logging and Audit Admin – Monitor and Troubleshoot

Developers

Dev – Overview Dev – Architecture Dev – Build a Store Service Dev – Service Manifest Reference Dev – API Reference Dev – Testing Dev – Install Internals

Decisions (ADRs)

ADR – 001 Store Images Are Signed and Verified by Cells ADR – 002 Named Connection Instances for Connectivity ADR – 003 All Optional Functionality Ships as Store Services

Meta

Meta – Glossary Meta – Template Runbook Meta – Template ADR

Archive

Archive – User Guide Archive – ADR 004 The Wiki Is the Single Documentation Source