CMS/BookStack@nginx-Debian12.md

@@ -1,22 +1,63 @@
 # HISTORY
 ```
 2024-05-24  * init and screen recording /A
+2024-11-23  + second instance for InstallAndUse.com /A
 ```
 
 
 TODO:
+- create empty DB
+```
+db: dox_installanduse_com-bookstack
+u:  dox_installanduse_com-bs_rw
+p:  xxxxxxxxxxxxxxxxxxx
+```
 
-- create DB (restore schema)
-- create user
 
-- create a bucket for storage
-create storage in Cloud Storge, Service account and key-secret pair
+- create service account to access bucket
+```
+bucket: dox_installanduse_com-bookstack
+user: dox-installanduse-com-bs-rw@projectname-333333.iam.gserviceaccount.com
 ```
-Cloud Storage, [create], do not expose to internet!
+
+- create a bucket for storage
+create storage in Cloud Storage, Service account and key-secret pair
+```
+Name: iau-data-dox
+Cloud Storage, [create],
+  Region: eu-north1
+  Choose a storage class for your data
+    [o] Autoclass
+      [x] Opt-in to allow object transitions to Coldline and Archive classes
+  Choose how to control access to objects:  Allow public access, [ ] Enforce public access prevention on this bucket
+  Access control: Fine-grained: Object-level ACLs enabled.
+
+Cloud storage, Buckets, iau-data-dox, Permissions, [Grant access]
+  New princtipals: dox-installanduse-com-bs-rw@projectname-333333.iam.gserviceaccount.com
+      Storage Legacy Bucket Owner
+      Storage Legacy Bucket Reader
+      Storage Legacy Bucket Writer
+      Storage Legacy Object Owner
+      Storage Legacy Object Reader
+      Storage Object Creator
+      Storage Object User
+      Storage Object Viewer
+
+Cloud Storage, Settings, Interoperability, [Create a key for another service account]
+  Service accountName: dox_installanduse_com-bs_rw, [Create key]
+  New key access key and secret will be shown only ONCE. Write it down.
+    dox-installanduse-com-bs-rw@projectname-333333.iam.gserviceaccount.com
+    Access key    GOOG1ETE423VPVxxxxxxxxxxxxxxxxxxxxxxxxxxxxxDAO5JMZZA7NKLG4S
+    Secret        xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+    Copy this key's secret if you'll need it in the future. Once you close this dialog, the secret can't be recovered.
+
+--or--
 Cloud Storage, Settings, Interoperability, [Create a key],  Service account HMAC [Create new account]
   Name: dox_2dz_fi-bookstack, [Create and continue]
   Roles: Storage Object Admin, [Continue], [Done]
   Save key and secret! Secret will be shown once.
+--or--
+
 ```
 
 
@@ -24,53 +65,41 @@ Cloud Storage, Settings, Interoperability, [Create a key],  Service account HMAC
 gsutil uniformbucketlevelaccess get gs://2dz-data-hub
 ```
 Expected output
-```
+```bash
 Uniform bucket-level access setting for gs://2dz-data-hub:
   Enabled: False
 ```
 
-- create a bucket user (GCP Service Account) with corresponding permissions
-```
-  IAM, Service accounts, [Create service account],
-  name: dox_2dz_fi-bookstack
 
- Grant access:
-    New principal:
-      dox_2dz_fi-bookstack@....gserviceaccount.com
-    Roles
-      Storage Object Creator
-      Storage Object User
-      Storage Object Viewer
-      ? Storage Object Creator
-
-      ?? more
-      ? Storage Legacy Bucket Owner
-      ? Storage Legacy Bucket Reader
-      ? Storage Legacy Bucket Writer
-      ? Storage Legacy Object Owner
-      ? Storage Legacy Object Reader
-      allUsers
-
-```
-Extract the secret for connection: (noted to KeePassXC)
-```
-
-```
 
 - create CNAME/A record, point to a server
 ```bash
 dig A dox.2dz.fi
+dig A dox.installanduse.com +short
 ```
 
-- create home directory (/home/bookstack)
-- clone code from repo
+- create home directory for application
 ```bash
+whoami
 sudo su
-cd /home
+# privileged user (you)
+export pu="anton"
+
+# working directory (for easy future maintenance)
+export wsd="/var/www/dox.installanduse.com"
+mkdir -p ${wsd}
+# permit priviledged user to own app directory
+chown -R ${pu}:${pu} ${wsd}
+exit
+# as priviledged user, not as root
+export wsd="/var/www/dox.installanduse.com"
+cd ${wsd}
+```
+
+clone latest application source code from repo
+```bash
 git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch
-mv /home/BookStack /home/dox_2dz_fi-bookstack
-chown -R anton:anton /home/dox_2dz_fi-bookstack/
-cd /home/dox_2dz_fi-bookstack/
+ls -la BookStack/
 ```
 
 Download composer and install in global mode (as normal user, not as root), later easy to update.
@@ -87,80 +116,122 @@ sudo mv composer.phar /usr/local/bin/composer
 
 - build (composer install)
 ```bash
-cd /home/dox_2dz_fi-bookstack/
+cd ${wsd}/BookStack
 which composer
 composer install --no-dev
 ```
 
-- configure .env
+Set least necessary permissions for webserver
 ```bash
 sudo su
-cd /home/dox_2dz_fi-bookstack/
-chown -R www-data:www-data storage/
-chmod -R 775 storage/
-chown -R www-data:www-data bootstrap/cache/
-chmod -R 775 bootstrap/cache/
-chown -R www-data:www-data public/uploads/
-chmod -R 775 public/uploads/
-chown -R www-data:www-data public/
+export wsd="/var/www/dox.installanduse.com"
+# webserver's user
+export wsu="www-data"
+chown -R ${wsu}:${wsu} ${wsd}/BookStack/storage/
+chmod -R 775           ${wsd}/BookStack/storage/
+chown -R ${wsu}:${wsu} ${wsd}/BookStack/bootstrap/cache/
+chmod -R 775           ${wsd}/BookStack/bootstrap/cache/
+chown -R ${wsu}:${wsu} ${wsd}/BookStack/public/uploads/
+chmod -R 775           ${wsd}/BookStack/public/uploads/
+chown -R ${wsu}:${wsu} ${wsd}/BookStack/public/
 ```
 
-``` credentials
-h: 172.21.32.6
-db: dox_2dz_fi-bookstack
-u: dox_2dz_fi-bookstack
-p: (see keepassXC)
 
+Copy template, generate salt abd configure .env
+```bash
+cp .env.example .env
+php artisan key:generate
+vi .env
+```
+```
+APP_KEY=base64:xxxxxxxxxxxxxxxxxxxxxxxxPbw8=
+APP_URL=https://dox.installanduse.com
+
+DB_HOST=172.21.xx.xx
+DB_DATABASE=dox_installanduse_com-bookstack
+DB_USERNAME=dox_installanduse_com-bs_rw
+DB_PASSWORD=xxxxxxxxxxxxxxxxxxx
 
+MAIL_DRIVER=smtp
+MAIL_FROM_NAME="dox.installanduse.com"
+MAIL_FROM=dox@installanduse.com
+MAIL_HOST=127.0.0.1
+MAIL_PORT=25
+MAIL_USERNAME=null
+MAIL_PASSWORD=null
+MAIL_ENCRYPTION=null
 MAIL_VERIFY_SSL=false
-```
 
-Generate salt (as normal user)
-```bash
-cd /home/dox_2dz_fi-bookstack/
-id
-php artisan key:generate
+STORAGE_TYPE=s3
+STORAGE_S3_KEY=GOOG1ETE423VPVUU3PBHxxxxxxxxxxxxxxxNZD3B4YDAO5JMZZA7NKLG4S
+STORAGE_S3_SECRET=4mUF0niGoHfenkxxxxxxxxxxxZCoUqCIiwpg89Evj
+STORAGE_S3_BUCKET=iau-data-dox
+STORAGE_S3_REGION=europe-north1
+STORAGE_S3_ENDPOINT=https://storage.googleapis.com
+STORAGE_URL=https://storage.googleapis.com/iau-data-dox
 ```
 
-- configure webserver (nginx)
-  - create site config
+
+# Configure webserver (nginx)
+
+create site config.
+
+Determine, where is PHP is listening to. It is very important, as I spent many hours many years ago to figure out, troubleshooting it. There are two ways to find the answer. You should use the most generic one, because after version upgrade, confgiration will remain functional.
 ```bash
 sudo su
-
 systemctl | grep php
 systemctl status php8.2-fpm.service
 less /lib/systemd/system/php8.2-fpm.service
 # observe for socket path
 ls -la /run/php/php-fpm.sock
+```
+```bash
 lrwxrwxrwx 1 root root 30 May 23 00:21 /run/php/php-fpm.sock -> /etc/alternatives/php-fpm.sock
+```
+```bash
 ls -la /etc/alternatives/php-fpm.sock
+```bash
 lrwxrwxrwx 1 root root 24 May 23 00:21 /etc/alternatives/php-fpm.sock -> /run/php/php8.2-fpm.sock
+```
+```bash
 ls -la /run/php/php8.2-fpm.sock
+```
+```bash
 srw-rw---- 1 www-data www-data 0 May 23 00:21 /run/php/php8.2-fpm.sock
 ```
-Check via configuration
+
+Or check via configuration
 ```bash
 fgrep -irn fpm.sock /etc/php/
 ```
 Determine from output location of socket
-```
+```bash
 /etc/php/8.2/fpm/pool.d/www.conf:41:listen = /run/php/php8.2-fpm.sock
 ```
 
+To summarize own findings, we shall use:
 ```bash
+/run/php/php-fpm.sock
+```
+
+
+```bash
+sudo su
+# copy output of root path
+echo ${wsd}/BookStack/public
 cd /etc/nginx/sites-available
-vi dox.2dz.fi.conf
+vi dox.installanduse.com.conf
 ```
 
-e.g.: (SSL will be enabled later by CertBot)
+Create a simple virtualhost configuration listining on http. SSL will be enabled later by CertBot.
 ```ini
 server {
   listen 80;
   listen [::]:80;
 
-  server_name dox.2dz.fi;
+  server_name dox.installanduse.com;
 
-  root /home/dox_2dz_fi-bookstack/public;
+  root /var/www/dox.installanduse.com/BookStack/public;
   index index.php index.html;
 
   location / {
@@ -175,77 +246,187 @@ server {
 ```
 
 
-- enable it
+- enable available site
 ```bash
-ln -s /etc/nginx/sites-available/dox.2dz.fi.conf /etc/nginx/sites-enabled/dox.2dz.fi.conf
+ln -s /etc/nginx/sites-available/dox.installanduse.com.conf /etc/nginx/sites-enabled/
+ls -latr /etc/nginx/sites-enabled
 ```
 
 Test webserver configuration, and reload it.
 ```bash
 nginx -t
 nginx -s reload
-systemctl restart nginx
+# systemctl restart nginx
 ss -ntap | grep nginx
 ```
 
 
 
-- upgrade DB (recreate/upgrade schema to the recent)
-```
-cd /home/dox_2dz_fi-bookstack/
+- upgrade DB (recreate/upgrade schema to the recent), approve warning on application in production (we are doing fresh deployment)
+```bash
+exit
+id
+export wd="/var/www/dox.installanduse.com"
+cd ${wsd}/BookStack
 php artisan migrate
 ```
-check DB
+
+
+Check DB
 ```bash
-mysql -h(host) -u dox_2dz_fi-bookstack -p
+mysql -h (dbhost) -u dox_installanduse_com-bs_rw -p
 ```
 ```sql
-MySQL [dox_2dz_fi-bookstack]> SHOW DATABASES;
-MySQL [dox_2dz_fi-bookstack]> USE dox_2dz_fi-bookstack;
-MySQL [dox_2dz_fi-bookstack]> SHOW TABLES;
-MySQL [dox_2dz_fi-bookstack]> SELECT * FROM users;
+MySQL [(none)]> SHOW DATABASES;
+[...]
+| dox_installanduse_com-bookstack |
+[...]
+MySQL [(none)]> USE dox_installanduse_com-bookstack;
+[...]
+Database changed
+MySQL [dox_installanduse_com-bookstack]> SHOW TABLES;
+[...]
+| users                                     |
+[...]
++-------------------------------------------+
+38 rows in set (0.003 sec)
+
+MySQL [dox_installanduse_com-bookstack]> SELECT * FROM users;
+[...]
+|  1 | Admin | admin@admin.com   | $2y$12$Hw/USVgBnbR2OEuSSaxxxxxxxxxxbPLUFcw8n98xjK.MP45K | NULL           | 2024-11-23 16:30:10 | 2024-11-23 16:30:10 |               1 |        0 |                  | NULL        | admin |
+[...]
+2 rows in set (0.003 sec)
+quit
+```
+
+After DB is built, main page of application should be accessible over HTTP, it will be automatically redirected to HTTPS and will not be possible to view via browser. But from CLI, it will be possible using curl:
+```bash
+curl http://dox.installanduse.com
 ```
-
-- Enable SSL using Let's Encrypt and Certbot
 ```bash
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="UTF-8" />
+        <meta http-equiv="refresh" content="0;url='https://dox.installanduse.com/login'" />
+
+        <title>Redirecting to https://dox.installanduse.com/login</title>
+    </head>
+    <body>
+        Redirecting to <a href="https://dox.installanduse.com/login">https://dox.installanduse.com/login</a>.
+    </body>
+</html>
+```
+
+It is possible to leave plain HTTP, but highly recommended enable SSL at the same time!
+- Enable SSL using Let's Encrypt and Certbot. Before doing that, let's ensure, that pointing FQDN match actual IP address.
+```bash
+curl https://myip.2dz.fi
+```
+```bash
+35.228.9.88
+```
+```bash
+dig A dox.installanduse.com +short
+```
+```bash
+installanduse.com.
+35.228.9.88
+```
+```bash
+sudo su
 apt install certbot python3-certbot-nginx
-certbot --nginx -d dox.2dz.fi
+certbot --nginx -d dox.installanduse.com
+```
+```bash
+Saving debug log to /var/log/letsencrypt/letsencrypt.log
+Requesting a certificate for dox.installanduse.com
+
+Successfully received certificate.
+Certificate is saved at: /etc/letsencrypt/live/dox.installanduse.com/fullchain.pem
+Key is saved at:         /etc/letsencrypt/live/dox.installanduse.com/privkey.pem
+This certificate expires on 2025-02-21.
+These files will be updated when the certificate renews.
+Certbot has set up a scheduled task to automatically renew this certificate in the background.
+
+Deploying certificate
+Successfully deployed certificate for dox.installanduse.com to /etc/nginx/sites-enabled/dox.installanduse.com.conf
+Congratulations! You have successfully enabled HTTPS on https://dox.installanduse.com
+
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+If you like Certbot, please consider supporting our work by:
+ * Donating to ISRG / Let's Encrypt:   https://letsencrypt.org/donate
+ * Donating to EFF:                    https://eff.org/donate-le
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+```
+```bash
 nginx -t
 systemctl restart nginx
-
 ```
 
 
-Application should be up and running
-```
-firefox https://dox.2dz.fi/
+Application should be up and running, open local browser
+```bash
+open -a firefox https://dox.installanduse.com/
 ```
 
 Login with default credentials:
 ```
-u: admin@admin.com
-p: password
+Email:    admin@admin.com
+Password: password
 ```
 
+Change admin email (do not delay, do it now.):
+```url
+https://dox.installanduse.com/my-account/profile
+```
 
 
+Change admin password and enroll MFA (good OTP manger is 'FreeOTP+' for Android):
+```url
+https://dox.installanduse.com/my-account/auth
+```
+
+Create your personal account (do not use admin account for daily operations)!
+```url
+https://dox.installanduse.com/settings/users/create
+```
+Logout, login,  enroll MFA!
+```url
+https://dox.installanduse.com/mfa/setup
+```
 
 
+# Fine-tuning:
+```bash
+vi .env
+```
 ```ini
 # File Upload Limit
 # Maximum file size, in megabytes, that can be uploaded to the system.
 FILE_UPLOAD_SIZE_LIMIT=50
 ```
+
+
+
 - S3 driver to mount storage in Cloud Bucket
 - fine-tune (nginx.conf)
+```bash
+vi /etc/nginx/nginx.conf
+```
 ```ini
+[...]
 http {
 	#...
         client_max_body_size 100m;
         client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
 	#...
 }
+[...]
 ```
+
+
+
 - fine-tune PHP
 ```bash
 ps aux | grep php
@@ -264,4 +445,30 @@ memory_limit = 256M
 ref.
 https://www.bookstackapp.com/docs/admin/installation/#requirements
 https://www.bookstackapp.com/docs/admin/upload-config/#s3
+```
+
+
+more notes on location os filesizes for upload
+```bash
+
+[08:23:12 Sat Nov 30] @gcp1mx1 /home/dox_2dz_fi-bookstack/storage/logs# fgrep -irn  post_max_size  /etc/php
+/etc/php/8.2/apache2/php.ini:703:post_max_size = 8M
+/etc/php/8.2/cli/php.ini:703:post_max_size = 8M
+/etc/php/8.2/fpm/php.ini:703:post_max_size = 8M
+vi /etc/php/8.2/apache2/php.ini
+vi /etc/php/8.2/fpm/php.ini
+vi /etc/php/8.2/cli/php.ini
+
+[08:23:48 Sat Nov 30] @gcp1mx1 /home/dox_2dz_fi-bookstack/storage/logs# fgrep -irn  upload_max_filesize  /etc/php
+/etc/php/8.2/apache2/php.ini:855:upload_max_filesize = 2M
+/etc/php/8.2/cli/php.ini:855:upload_max_filesize = 2M
+/etc/php/8.2/fpm/php.ini:855:upload_max_filesize = 2M
+vi /etc/php/8.2/apache2/php.ini
+vi /etc/php/8.2/cli/php.ini
+vi /etc/php/8.2/fpm/php.ini
+
+systemctl | grep fpm
+systemctl restart php8.2-fpm.service
+systemctl restart nginx
+
 ```