Update pivilion manual setup

pivilion-manual-setup.md

@@ -10,13 +10,13 @@ The base methodology of achieving this is allowing less experienced and communit
 By removing the gallery sites from the blogs and domains to a physical gadget of the Pi - Pivilion engages & connects users on two levels of interaction - virtual and physical, ideological and technical.
 The interaction with Pivilion could further concepts of freedom, education and spark collaborative potentials of one’s communities.
 
-It runs on top of Raspberry Pi 1, 2, 3 or Zero hardware and is built on top of Raspbberry Pi OS GNU/Linux. It has Apache server and Tor networking built in and uses the Tor network to host exhibitions out of the box.
+It runs on top of Raspberry Pi 1, 2, 3, 4 or Zero W / 2 hardware and is built on top of Raspbberry Pi OS GNU/Linux. It has Apache server and Tor networking built in and uses the Tor network to host exhibitions out of the box.
-The entire system and documentation is available for download on a central website, hosted both on clearnet and on the Tor network and distributed as SD card images available for free download. The website serves as both a central point for deployment of the system and for the announcement of global exhibitions running on nodes. It is designed so that the user-curator can use any network (even public networks behind firewalls) to host an exhibition.
+The entire system and documentation is available for download on a central website, hosted both on clearnet and on the Tor network. The website serves as both a central point for deployment of the system and for the announcement of global exhibitions running on nodes. It is designed so that the user-curator can use any network (even public networks behind firewalls) to host an exhibition.
-Each Pivilion device receives a Tor onion domain automatically the first time it’s activated. The system provides the user with backend access to a system for publishing images, videos or websites within a gallery. The gallery runs on a CMS designed specially for hosting online gallery events, with features such as different rooms, complete with Mozilla’s Togetherjs integrated into each seperate room.
+Each Pivilion device receives a Tor onion domain automatically the first time it’s activated. The system provides the user with backend access to systems for publishing media on the web.
 
 ## About This Manual
-This manual shows how to install Pivilion on your Raspberry Pi from scratch and use it as a portable darknet gallery. It installs Tor with Apache as a hidden service and runs a simple PHP based gallery system.
+This manual shows how to install Pivilion on your Raspberry Pi from scratch and use it as a portable darknet or local network gallery. It installs Tor with Apache as a hidden service and offers scripts to help facilitate the download and installation of web publication tools.
-It's recommended to read through the entire manual, before attempting to install it on a Raspberry Pi. 
+It's recommended to read through the entire manual before attempting to install it on a Raspberry Pi. 
 
 Tor is free software for enabling anonymous communication and censorship circumvention. However, Pivilion doesn't use Tor for its anonimity features (but Tor still provides them). Tor is used to host a HTTP server as a hidden service. We make extensive use of its NAT punching capabilites to enable us to host a gallery behind NATs and firewalls. Keep in mind that this may or may not break your ISP contract if you do it from home. Using public WiFi to host hidden services, while not technically illegal if you were provided with the password by the owner of the WiFi,  may present certain issues with their ISP.  Since we're using Tor there is no way for you to get *caught*. With great power comes great responsibility. Be responsible in what you host and do on the darknet while using Pivilion.
 
@@ -27,19 +27,19 @@ Tor is free software for enabling anonymous communication and censorship circumv
 1. Min 8 GB (micro)SD card
 1. SD card reader (and a microSD to SD adapter if necessary)
 1. Ethernet cable (or proper wpa_supplicant.conf to connect to WiFi with Pi Zero - generate one [here](https://wifi.pivilion.net/))
-1. HDMI cable - optional 
+1. HDMI cable - for connection to a screen - optional 
 
 You can connect the RPi to a HDMI screen (with a USB mouse + keyboard) and connect it to WiFi as you would any computer. However, this setup is meant to be made over SSH - consider your Pi a server (even though it's on a table next to you :)). You can connect it to a display and once you input the WiFi password, just connect to the Pi via SSH from a different computer.
 
 ### Software
-1. [Raspberry Pi OS Legacy image](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy) - the "lite" image is recomkended for Pivlion - note that this version doesn't have a graphical user interface installed - you can only use the terminal interface if you connect the Pi to a screen with a HDMI cable. We are using the Legacy image while we iron out some trouble with captive portal mode.
+1. [Raspberry Pi OS Legacy image](https://www.raspberrypi.com/software/operating-systems/#raspberry-pi-os-legacy) - the "lite" image is recomkended for Pivlion - note that this version doesn't have a graphical user interface installed - you can only use the terminal interface if you connect the Pi to a screen with a HDMI cable. We are using the Legacy image while we iron out some problems with captive portal mode.
 1. [Tor Browser](https://www.torproject.org/download/download-easy.html.en) - used only for checking if the gallery works on Tor (not for generating galleries)
 1. A network scanning tool like [Nmap](https://nmap.org/) or Fing (avaliable for iOS and Android) **Be careful with network scanning software - scanning networks that are not yours may be illegal in your country!**  
 1. [Putty SSH client](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) - Windows only
 1. [Filezilla sFTP client](https://filezilla-project.org/) - optional, for backing up and uploading files to the Pi
 
 ## Software Installation
-Pivilion runs on top of libre / free software which is avaliable in the Raspbberry Pi OS repositories. To download and install software we will use APT. Advanced Package Tool. Apt is a free-software user interface that works with core libraries to handle the installation and removal of software on Debian, Ubuntu, and related Linux distributions.
+Pivilion runs on top of libre / free software which is avaliable in the Raspbberry Pi OS repositories. To download and install software we will use apt, the Advanced Package Tool. Apt is a free software user interface that works with core libraries to handle the installation and removal of software on Debian, Ubuntu, and related Linux distributions (Raspbnerry Pi OS is based on Debian).
 
 ### Installing Raspbperry Pi OS
 Always get a current Raspbperry Pi OS Legacy image before installing Pivilion. It will drastically speed up the update / upgrade step of the manual. Use the guide on [this](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) page to determine how to handle images on your OS. We’ll be using Linux + dd.
@@ -50,17 +50,17 @@ SSH access is turned off by default for security. We need to do a simple extra s
 The boot partition on a Pi should be accessible from any machine with an SD card reader, on Linux, Windows or Mac. If you want to enable SSH, all you need to do is to put a file called ssh in the boot partition. The contents of the file don’t matter: it can contain any text you like, or even nothing at all. When the Pi boots, it looks for this file; if it finds it, it enables SSH and then deletes the file. SSH can still be turned on or off from the Raspberry Pi Configuration application or raspi-config; this is simply an additional way to turn it on if you can’t easily run either of those applications.
 
 ### Connecting to the Pi
-Once that’s done, connect your RPi to a DHCP network and power it on. Depending on your network configuration, you can login to your RPi using it's hostname "raspberry", or use a network discovery tool to find it's IP address.
+Once that’s done, connect your RPi to a DHCP network and power it on. Depending on your network configuration, you can login to your RPi using it's hostname "raspberry", use a network discovery tool to find it's IP address, or check your router administrator intarface for the ip assigned to your Pi.
 
 #### Using WiFi Only to Connect to the Pi
 
-If a physical network connection is unavailable or you're using the Raspberry Pi Zero W that uses wireless networking only, you need to generate a wpa_supplicant.conf file and use a card reader to place the file in the root of the FAT32 formatted boot partition of your RPi SD card. You can do this manually or generate a conf file with a generator at the following URL. https://wifi.pivilion.net/
+If a physical network connection is unavailable or you're using the Raspberry Pi Zero W / 2 that uses wireless networking only, you need to generate a wpa_supplicant.conf file and use a card reader to place the file in the root of the FAT32 formatted boot partition of your RPi SD card. You can do this manually or generate a conf file with a generator at the following URL. https://wifi.pivilion.net/
 
 wpa_supplicant is a free software implementation of an IEEE 802.11i supplicant for Linux, FreeBSD, NetBSD, QNX, AROS, Microsoft Windows, Solaris, OS/2 (including eComStation) and Haiku. In addition to being a fully featured WPA2 supplicant, it also implements WPA and older wireless LAN security protocols.
 
 The config file generated will assume you're using WPA2 security on your network. If not, you will have to modify it manually according to your network settings.
 
-It also adds a country code to your WiFi settings which Raspbperry Pi OS made mandatory for the RPi 3b+ and it has been known to cause issues for some people. In the generated config file the country will be set to Bolivia which will allow you to push your WiFi to higher power then legally allowed in your country. If you feel uneasy about this please change this to your country code. Note that your Pi won't automatically transmit at a higher rate without being instructed to do so, but that's outside the scope of this document.
+It also adds a country code to your WiFi settings which Raspbperry Pi OS made mandatory for the RPi 3b+ and it has been known to cause issues for some people. In the generated config file the country will be set to Bolivia which will allow you to push your WiFi to higher power then legally allowed in some countries. If you feel uneasy about this please change this to your country code. Note that your Pi won't automatically transmit at a higher rate without being instructed to do so, but that's outside the scope of this document.
 
 #### Finding the Pi's IP 
 
@@ -123,9 +123,9 @@ Apache is a free and open-source cross-platform web server software, released un
 
 You can now navigate to your RPi's IP (or hostname - raspberry) using a browser.
 
-You will see lighttpd's placeholder page.
+You will see Apache's placeholder page.
 
-### Installing PHP and Modules
+### Installing PHP
 
 `sudo apt install php -y`
 
@@ -257,7 +257,7 @@ Tor will generate a hostname. To view your hostname run
 Check if your hidden service works by opening Tor Browser and navigating to your onion domain.   
 (In case you'd like a vanity .onion address, there is [a way](https://github.com/lachesis/scallion) to customize it afterwards.)
 
-This should show the same lighttpd placeholder page as before. 
+This should show the same Apache placeholder page as before. 
 
 That's it - everything should be working now! 
 
@@ -273,8 +273,15 @@ All these commands are bash scripts located in the /usr/local/bin directory.
 It will also redirect all non-encrypted traffic to this IP, meaning that all traffic will be redirected to your gallery. You can use this mode to serve a local instance of the gallery. 
 **Please remember to set the mode properly before each reboot or you might have to access your Pi via ethernet cable or screen.**
 1. "pikey" is used to setup a WiFi network and password to be used in onion mode. 
+1. "hotglue" is used to install or restore a hotglue installation
+1. "static" is used to convert hotglue into a static website
+1. "generator" will enable the pivilion generator on port 81
 
-### Using the Generator Script to Setup a Gallery
+### Using Hotglue to Setup a website
+
+Hotglue is a unique tool for web publication & samizdat. It has a fun to use interface and is a community project. It also has some security issues and that's why we convert it to static HTML before serving it on the darknet. Websites generated with the generator script all look the same so this si the prefered way to setup a website when not using full custom HTML / javascript. In order to install or revert hotglue 
+
+### Using the Generator Script to Setup a website
 
 After setting everything up, you can find the generator script by entering your Pi's IP address into your browser on port 81. This is only available on your local network, not through Tor - e.g. http://192.168.1.5:81.
 
@@ -286,9 +293,9 @@ The gallery generator takes in some basic data such as the name, description, ti
 
 ### Changing PHP file size limits
 
-If you need to upload larger files, or more files at once, you can edit the file /etc/php/7.3/cgi/php.ini with 
+If you want to change file size limits, you can edit the php.ini file with 
 
-`sudo nano /etc/php/*version_number*/cgi/php.ini`
+`sudo nano /etc/php/7.3/apache2/php.ini`
 
 There you will find options such as 
 
@@ -296,13 +303,73 @@ There you will find options such as
 `upload_max_filesize`
 `max_file_uploads`
 
-You can observe their values and read the comments around them to figure out what they do and what inputs they take. After it's adjusted you need to restart Lighty with
+You can observe their values and read the comments around them to figure out what they do and what inputs they take. After it's adjusted you need to restart Apache with
 
 `sudo service apache2 force-reload`
 
+### Server Directory Breakdown
+
+The Pivilion Apache configuration keeps all its files in 
+
+'
+/var/www/html/pivilion/
+|-- gen --> data that apache serves to  clients (hotglue files, static HTML or your own website data go here)
+|   `--- .htaccess --> file that handles redirects (very important for hotspot mode, very important that it isn't there in onion mode)
+|-- gen.php --> generator script main PHP file
+|-- images --> generator scirpt images
+|-- index.html --> HTML layout for generator script
+|-- scripts --> scripts for generator script
+`-- skeleton --> files that are copied into galleries generated by the generator script
+'
+
+### .htaccess File Breakdown
+
+When running in hotspot mode the system makes use of redirect rules that are quire important because all requests need to be redirected in order for client machines to register the captive portal and open it in the browser. There rules are set by the .htaccess file in the /var/www/html/pivilion/gen directory (the server directory). The rules set here are for allowing access to Hotglue and  Generator Script files (queries to all other files will be redirected to http://10.1.1.1/index.php). 
+
+**When uploading custom HTML and using hotspot mode adjusting this file file accordingly is required** (it will not work otherwise)
+
+Allowing access to a file:
+
+'RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$'
+
+This allows access to the file "pi_logo_128.png" in the directory the .htaccess file resides in.
+
+Allowing access to a directory:
+
+'RewriteCond %{REQUEST_URI} !(\/img\/.*)$'
+
+This allows access to the directory "img" in the directory the .htaccess file resides in (and any / all files inside it). 
+
+Default .htaccess for reference:
+
+'
+RewriteEngine on
+RewriteCond %{REQUEST_URI} !(\/index\.php)$
+RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$
+RewriteCond %{REQUEST_URI} !(\/content\/.*)$
+RewriteCond %{REQUEST_URI} !(\/index\.php)$
+RewriteCond %{REQUEST_URI} !(\/pi-logo_128\.png)$
+RewriteCond %{REQUEST_URI} !(\/content\/.*)$
+RewriteCond %{REQUEST_URI} !(\/css\/.*)$
+RewriteCond %{REQUEST_URI} !(\/doc\/.*)$
+RewriteCond %{REQUEST_URI} !(\/docker\/.*)$
+RewriteCond %{REQUEST_URI} !(\/img\/.*)$
+RewriteCond %{REQUEST_URI} !(\/js\/.*)$
+RewriteCond %{REQUEST_URI} !(\/modules\/.*)$
+RewriteCond %{REQUEST_URI} !(\/tests\/.*)$
+RewriteCond %{REQUEST_URI} !(\/*.php)$
+RewriteRule ^(.*)$ http://10.1.1.1/index.php [L,R=301]
+'
+
+The last line 
+
+'RewriteRule ^(.*)$ http://10.1.1.1/index.php [L,R=301]'
+
+shoudl always be kept!
+
 ### Custom HTML
 
-You can also choose to overwrite anything the generator script generates or edit it manually just like you would HTML / PHP on any server. Use an FTP client such as [Filezilla](https://filezilla-project.org/) and the same username / password you would for logging in via SSH (point Filezilla to your Pi's IP and port 22). The directory that's served is /var/www/html/pivilion/gen. You can also edit Lighty's config in /etc/ lighttpd.conf and move the directory to where you see fit.
+You can also choose to overwrite anything the generator script generates or edit it manually just like you would HTML / PHP on any server. Use an FTP client such as [Filezilla](https://filezilla-project.org/) and the same username / password you would for logging in via SSH (point Filezilla to your Pi's IP and port 22). The directory that's served is /var/www/html/pivilion/gen. You can also edit Apache's config in /etc/apache2/ and move the directory to where you see fit.
 
 ### Backing Up HTML Content
 
@@ -358,7 +425,7 @@ You can also download the complete pre-installed appliance image and run Pivilio
 If you don't feel like learning about the various components used to build a Tor hidden service, you can just use lazy mode to bundle up individual installations.
 All you need to do is paste the following line into your terminal and hit Enter. It will take a couple of minutes to finish.
 
-`sudo apt update; sudo apt upgrade -y; sudo apt install apache2 php hostapd dnsmasq git tor zip -y; cd /; sudo git init; sudo git remote add origin https://gitlab.com/hacklab01/pivilion.git; sudo git fetch origin; sudo git checkout -f --track origin/master; sudo chown -R pi:pi /home/pi; sudo chown -R www-data:www-data /var/www/; sudo chmod -R 775 /var/www; sudo usermod -a -G www-data pi; onion; pivilion; sudo reboot`
+`sudo apt update; sudo apt upgrade -y; sudo apt install apache2 php hostapd dnsmasq git tor zip -y; cd /; sudo git init; sudo git remote add origin https://gitlab.com/hacklab01/pivilion.git; sudo git fetch origin; sudo git checkout -f --track origin/master; sudo chown -R pi:pi /home/pi; sudo chown -R www-data:www-data /var/www/; sudo chmod -R 775 /var/www; sudo usermod -a -G www-data pi; onion; sudo reboot`
 
 The system will reboot automatically and all you need to do is run