Create user and group
---------------------
Credentials -> Local Users -> Add
Full Name: git
Username: git
Disable Password: <selected>
Email: <leave blank>
UID: 1000
Create New Primary Group: <unselected>
Create Home Directory: <unchecked>
Samba Authentication: <unchecked>
Save
Credentials -> Local Groups -> Add
Name: git
GID: 1000

PUID: 1000
PGID: 1000
Update .env file accordingly (PUID, PGID)

Create datasets
---------------
# In Truenas shell:
# list datasets
zfs list | grep -i "docker.*gitea"
# create following datasets if not present
zfs create SSD1/docker/data/gitea
zfs create SSD1/docker/data/gitea/appdata
zfs create SSD1/docker/data/gitea/backups
zfs create SSD1/docker/data/gitea/pgdata
zfs create SSD1/docker/data/gitea/pgbackups
chown -R git:git /mnt/SSD1/docker/data/gitea
chown -R postgres:postgres /mnt/SSD1/docker/data/gitea/pgdata
chown -R postgres:postgres /mnt/SSD1/docker/data/gitea/pgbackups

Create folder
-------------
# In Truenas shell:
mkdir -p /mnt/SSD1/docker/stacks/gitea/secrets

Create secrets
--------------
In Truenas shell:
cd /mnt/SSD1/docker/stacks/gitea/secrets/
# database secrets
echo -n 'gitea' > /mnt/SSD1/docker/stacks/gitea/secrets/gitea_postgresql_database
echo -n 'gitea' > /mnt/SSD1/docker/stacks/gitea/secrets/gitea_postgresql_username
openssl rand 36 | base64 -w 0 > /mnt/SSD1/docker/stacks/gitea/secrets/gitea_postgresql_password
# smtp email secrets
echo -n 'your_smtp_destination' > /mnt/SSD1/docker/stacks/gitea/secrets/smtp_destination
echo -n 'your_smtp_from' > /mnt/SSD1/docker/stacks/gitea/secrets/smtp_from
echo -n 'your_smtp_host' > /mnt/SSD1/docker/stacks/gitea/secrets/smtp_host
echo -n 'your_smtp_username' > /mnt/SSD1/docker/stacks/gitea/secrets/smtp_username
echo -n 'your_smtp_password' > /mnt/SSD1/docker/stacks/gitea/secrets/smtp_password
# restrict access
chown -R git:git /mnt/SSD1/docker/stacks/gitea/secrets/
chmod -R 400 /mnt/SSD1/docker/stacks/gitea/secrets/
# read existing acl permissions, if any
getfacl /mnt/SSD1/docker/stacks/gitea/secrets
# set acl permissions
setfacl -m u:postgres:4 /mnt/SSD1/docker/stacks/gitea/secrets
setfacl -m u:postgres:4 /mnt/SSD1/docker/stacks/gitea/secrets/gitea_postgresql_password
setfacl -m u:postgres:4 /mnt/SSD1/docker/stacks/gitea/secrets/gitea_postgresql_username
setfacl -m u:postgres:4 /mnt/SSD1/docker/stacks/gitea/secrets/gitea_postgresql_database
# NB! if you want to remove all acl entries from a folder recursively, use setfacl -b -R <foldername>
# to list secrets in secrets dir
cd /mnt/SSD1/docker/stacks/gitea/secrets
for i in $(ls -1); do echo $i = `cat $i`; done | sort

Copy folder to docker stacks
----------------------------
In Windows cmd shell in gitea parent (apps) folder, enter:
./cp2nas 10.0.0.20 gitea
# or
pscp -P 22 -r gitea/stacks/*.* root@10.0.0.20:/mnt/SSD1/docker/stacks/gitea/

Backup gitea database
---------------------  
In truenas shell:
mkdir /mnt/stpool1/apps/pgadmin/storage/stuurmcp_telkomsa.net/$(date -I)
chown pgadmin:pgadmin /mnt/stpool1/apps/pgadmin/storage/stuurmcp_telkomsa.net/$(date -I)

Using browser log in to pgAdmin
Connect to servers; refer to "connecting to servers.txt", which also explains how to obtain db passwords
To perform plain text backup:
Navigate to Servers => gitea -> Databases -> gitea
Right click on gitea database and select Backup...
Enter the following on the different tabs of dialog box that opened:
General:
Replace ##### with today's date in YYYY-MM-DD format
Filename: /#####/gitea-backup.sql (this maps to: /mnt/stpool1/apps/pgadmin/storage/stuurmcp_telkomsa.net/#####/gitea-backup.sql on truenas)
Format: Plain
Encoding: UTF8
Role name: gitea
Data Options:
Sections:
Pre-data: <select>
Data: <select>
Post-data: <select>
Objects:
Check public to select all objects
Click Backup

Copy archive to pgbackup folder:
cp -vr /mnt/stpool1/apps/pgadmin/storage/stuurmcp_telkomsa.net/$(date -I) /mnt/SSD1/docker/data/gitea/pgbackups/

Migrating database
------------------
docker stop gitea
# copy back up file(s) to gitea backups folder
cp -vr /mnt/stpool1/apps/pgadmin/storage/stuurmcp_telkomsa.net/$(date -I) /mnt/SSD1/docker/data/gitea/backups #replace $(date -I) with date when backup was made if not today
jlmkr shell docker
docker exec -it gitea_postgresql sh
psql -U gitea -d gitea < /mnt/backups/$(date -I)/gitea-backup.sql #replace $(date -I) with date when backup was made if not today
exit

Backup data folder
------------------
Is is advisable to also backup the data folder. We'll do it before the gitea data dump
Stop gitea app:
heavyscript app --stop gitea
Use tar to backup:
cd /mnt/stpool1/appdata/gitea/
tar -zcf $shared/Chris/gitea/backup-$(date -I).tar.gz ./
heavyscript app --start gitea

Dumping gitea data
------------------
List gitea pods to check if they are running. If not, wait for the container to start:
k3s kubectl get pods -n ix-gitea
If all are ok, the listed containers should resemble the following:
NAME                               READY   STATUS    RESTARTS   AGE
gitea-cnpg-main-1                  1/1     Running   0          3h44m
gitea-memcached-6555987b5c-cl5l6   1/1     Running   0          3h44m
gitea-5d578f4988-8ht9r             1/1     Running   0          3h44m

Perform gitea dump using namespace, pod name and container name:
k3s kubectl exec -n ix-gitea gitea-5d578f4988-8ht9r -c gitea -it -- gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump-$(date -I) --type zip 
Copy backup archive from container to backup folder:
k3s kubectl cp -c gitea ix-gitea/gitea-5d578f4988-8ht9r:/tmp/gitea-dump-$(date -I).zip /mnt/SSD1/docker/data/gitea/backups/gitea-dump-$(date -I).zip 
k3s kubectl exec -n ix-gitea gitea-5d578f4988-8ht9r -c gitea -it -- rm -v /tmp/gitea-dump-$(date -I).zip

Restore to new gitea(Docker rootless)
-------------------------------------
Refer to: https://docs.gitea.com/administration/backup-and-restore
jlmkr shell docker
cd /mnt/data/gitea/backups
# copy container app.ini, if required later
docker cp gitea:/etc/gitea/app.ini ./app-new.ini  # container api.ini should be the file in /mnt/data/gitea/config

chown 1000:1000 gitea-dump-2024-09-04.zip
# with newly installed gitea running, unzip backup in container
docker exec --user git -it gitea unzip /mnt/backups/gitea-dump-$(date -I).zip -d /mnt/backups/temp/
# since we have nano in docker shell, we will edit app.ini here 
nano /mnt/data/gitea/backups/temp/app.ini
# change the work path to match the folder in the gitea container that ${DATADIR}/appdata is mapped to, i.e. /var/lib/gitea	
# change all paths to relative paths (inside work path)
# change tmp path to relative path (inside work path)
# the result should resemble following:
WORK_PATH = /var/lib/gitea
[repository]
ROOT = git/gitea-repositories
[server]
APP_DATA_PATH = /var/lib/gitea
CERT_FILE = gitea/https/gitea-sthome_org_cert.pem
KEY_FILE = gitea/https/gitea-sthome_org_key.pem
ACME_CA_ROOT = gitea/https/ca-cert-sthome_ca2.pem
[log]
ROOT_PATH = log
# change database password and host, after editing, the database stanza host line should resemble the following:
[database]
HOST = gitea_postgresql:5432
PASSWD = ioZ7lrzzMNcqLEr54sd5XMCe52E5OD7fD9BgS/MCh1DHNwH7
# change server domains,urls, etc.; after editing, the relevant server stanza lines should resemble the following:
[server]
DOMAIN = gitea.sthome.org
ROOT_URL = https://gitea.sthome.org/
SSH_DOMAIN = gitea.sthome.org
CERT_FILE = /data/gitea/https/gitea-sthome_org_cert.pem
KEY_FILE = /data/gitea/https/gitea-sthome_org_key.pem
ACME_URL = https://acme-v02.api.letsencrypt.org/directory
# add mailer stanza:
[mailer]
ENABLED        = true
FROM           = stuurman30@telkomsa.net
PROTOCOL       = smtp
SMTP_ADDR      = smtp.telkomsa.net
SMTP_PORT      = 25
USER           = stuurman30@telkomsa.net
PASSWD         = UltraM3!2024#
# save and exit

# ensure correct permissions for app.ini
chown 1000:1000 /mnt/data/gitea/backups/temp/app.ini
chmod 600 /mnt/data/gitea/backups/temp/app.ini
# open bash session in container
docker exec --user git -it gitea bash
cd /mnt/backups/temp
# restore the app.ini
cp -vp app.ini /etc/gitea/app.ini
# restore the gitea data
cp -vpr data/* /var/lib/gitea
# restore the repositories itself
cp -vpr repos/* /var/lib/gitea/git/repositories
# adjust file permissions
chown -R git:git /etc/gitea/app.ini /var/lib/gitea
# Regenerate Git Hooks
/usr/local/bin/gitea -c '/etc/gitea/app.ini' admin regenerate hooks

Starting up new gitea
---------------------
If gitea and postgresql containers are healthy in Dockge, browse to gitea.sthome.org
An Initial Configuration page will open
To get postgress and smtp passwords:
cat /opt/stacks/gitea/secrets/gitea_postgresql_password && echo && cat /opt/stacks/gitea/secrets/smtp_password && echo
Enter the db password under Database Settings 
Enter smtp password under Optional Settings -> Email Settings
Complete Administrator Account Settings
Click Install Gitea at the bottom
If it complains about You are trying to install into an existing Gitea database
Check the three checkboxes and click Install Gitea

If your avatars are missing, you can go to Settings and click on Delete Current Avatar to reset avatar to generated one


[repository.local]
LOCAL_COPY_PATH = /tmp/gitea/local-repo

[repository.upload]
TEMP_PATH = /tmp/gitea/uploads

Troubleshooting
---------------
# To check gitea log (if logging to file), enter:
tail -n50 /mnt/data/gitea/appdata/data/log/gitea.log -f
# note the time of the last entry
# If gitea is logging persistent "Error: pq: password authentication failed for user "gitea"":
# In docker shell, enter:
docker exec gitea-gitea-1 gitea doctor check
# this should display if user with wrong type exist
# If it shows an error, do the following to double check gitea instance of postgresql:
# In docker shell, exec into gitea postgresql container:
docker exec -it gitea-postgresql-1 bash
# In postgresql container shell, enter:
psql -U gitea -d gitea
# See if you get gitea prompt; if you do, then gitea user and gitea db is ok
# In gitea db shell list schemas (it should show "public"), enter:
\dn
# and to list roles, enter:
\du
# exit twice to get back to docker shell
# if anything appears wrong, rectify. However, if schemas and roles are ok, you need to check further...
# BTW, a subsequent doctor check now might show that the error is gone, but don't be fooled; it will return if gitea is restarted
# One other problem might be that there could be a clash with postgresql hostnames on the docker network. 
# Check whether the GITEA__database__HOST setting in the compose.yml points to a unique postgresql instance. 
# Fix it if it looks suspect. Restart gitea with updated compose.yml and check log again for errors (from the above noted time onwards)
tail -n50 /mnt/data/gitea/appdata/data/log/gitea.log -f