mirror of
https://gitlab.com/hacklab01/pivilion.git
synced 2026-08-06 16:08:22 +00:00
85 lines
4.7 KiB
Markdown
85 lines
4.7 KiB
Markdown
[Manual](https://gitlab.com/hacklab01/pivilion/wikis/pivilion-manual-setup)
|
||
|
||
Pivilion is a decentralizing open source darknet web server project and gallery management software for the creation of autonomous & uncensored digital media art online galleries. It runs on low cost Raspberry Pi hardware and is built on top of Raspbian GNU/Linux with a server and Tor networking built in, utilizing the Tor network to host exhibitions out of the box.
|
||
|
||
Each Pivilion device receives a Tor onion domain automatically the first time it’s activated. The system provides the user with a CMS for publishing multimedia or websites within a gallery. It’s designed so that the author-curator can use any network (even public networks behind firewalls) to host an online exhibition.
|
||
|
||
Pivilion is primarily a long-term, open-ended new media art project propagating autonomous modes of art in the darknet, and is continuously including a large number of artists and cultural workers in its creation.
|
||
|
||
The documentation and the announcement of global #pivilion_dot events are available via the central website, hosted both on clearnet and as a hidden service on the Tor network, while the entire open source system is available via git.
|
||
|
||
Project website: [pivilion.net](https://pivilion.net/)
|
||
|
||
Required hardware:
|
||
|
||
- Raspberry Pi with WiFi
|
||
- min 8 GB SD card
|
||
- battery or power adapter
|
||
|
||
## Installation on current Raspberry Pi OS
|
||
|
||
Pivilion supports Raspberry Pi OS Bullseye, Bookworm, and Trixie. Bookworm and
|
||
newer systems use NetworkManager automatically; Bullseye installations using
|
||
`dhcpcd` use the legacy hostapd backend. The repository layout and the original
|
||
commands are preserved on both backends.
|
||
|
||
On a fresh Raspberry Pi OS Lite installation:
|
||
|
||
```sh
|
||
git clone https://gitlab.com/hacklab01/pivilion.git
|
||
cd pivilion
|
||
sudo ./install.sh
|
||
sudo reboot
|
||
```
|
||
|
||
The installer performs preflight checks, backs up managed configuration under
|
||
`/var/backups/pivilion`, validates the deployed services, and restores the
|
||
previous configuration if deployment fails. Additional maintenance modes are:
|
||
|
||
```sh
|
||
./install.sh --dry-run # read-only preflight and proposed actions
|
||
sudo ./install.sh --check # validate an existing installation
|
||
sudo ./install.sh --repair # repeat deployment without replacing gallery content
|
||
```
|
||
|
||
The installer defaults to the user that invoked `sudo`, not to a hard-coded
|
||
`pi` account. The installer automatically creates `pivilion.conf` at the
|
||
externally visible root of the FAT boot partition, using the current system and
|
||
saved Wi-Fi settings. Linux may mount that same root as `/boot` or
|
||
`/boot/firmware`; users never need to expose that distinction. The hotspot is
|
||
intentionally open and passwordless.
|
||
|
||
The boot file controls startup mode, upstream Wi-Fi SSID and PSK, Wi-Fi country
|
||
and interface, hotspot name and channel, hostname, Pivilion user and paths,
|
||
generator state, and PHP upload limit. Pivilion commands keep it synchronized.
|
||
An 8–63-character Wi-Fi password entered there is replaced at boot with its
|
||
derived 64-character WPA PSK. The PSK does not reveal the original text, but it
|
||
still grants network access and must be treated as a secret. Invalid offline
|
||
edits retain the root-protected last-known-good settings and create
|
||
`pivilion-error.txt` beside the boot configuration.
|
||
|
||
Use `pikey` to save upstream Wi-Fi credentials, then `onion` and reboot to host
|
||
through Tor. Use `hotspot` and reboot to run the local captive gallery at
|
||
`http://10.1.1.1/`. HTTPS interception is intentionally not attempted because a
|
||
local captive portal cannot present valid certificates for arbitrary sites.
|
||
Changing `PIVILION_MODE` in the boot-partition configuration activates either
|
||
mode during the immediately following boot; no second reboot is required.
|
||
|
||
If a phone joins but does not open its captive-login window, run
|
||
`pivilion diagnose` on the Pi to verify DHCP/DNS, Apache rewrite handling,
|
||
nftables, and the common Android, Apple, and Microsoft HTTP probes.
|
||
|
||
`pivilion status` distinguishes the requested next-boot mode from the last
|
||
verified active mode and reports degraded activation. `pivilion diagnose
|
||
--json` provides the same health checks for monitoring. The legacy
|
||
`pivilion-diagnose` command remains an alias.
|
||
|
||
On the physical TTY, Pivilion appends its current IP, ASCII logo, and system
|
||
status through `/etc/issue.d/90-pivilion.issue`; Raspberry Pi OS retains its
|
||
normal Debian/hostname/TTY heading. The banner appears before `login:` rather
|
||
than among systemd boot messages. SSH sessions receive the same status once
|
||
after authentication.
|
||
|
||
Diagnostic exit codes are stable: `10` invalid configuration, `11` missing or
|
||
unsupported hardware, `12` service/port conflict, `13` core service failure,
|
||
`14` captive portal failure, `15` Tor/onion failure, and `20` installer failure.
|