https and migration

Adds environment vars to support HTTPS.

Adds documentation:

* enabling HTTPS
* migrating existing repositories

Signed-off-by: Phill Kelley <[email protected]>

Author: Paraphraser

.templates/gitea/service.yml

@@ -12,9 +12,13 @@ gitea:
     - GITEA__database__NAME=${GITEA_DB_NAME:-gitea}
     - GITEA__database__USER=${GITEA_DB_USER:-gitea}
     - GITEA__database__PASSWD=${GITEA_DB_PASSWORD:?eg echo GITEA_DB_PASSWORD=userPassword >>~/IOTstack/.env}
+    - GITEA__server__PROTOCOL=${GITEA_WEB_PROTOCOL:-http}
     - GITEA__server__ROOT_URL=${GITEA_ROOT_URL}
+  # - GITEA__server__KEY_FILE=/data/git/key.pem
+  # - GITEA__server__CERT_FILE=/data/git/cert.pem
     - GITEA__security__INSTALL_LOCK=true
     - GITEA__security__SECRET_KEY=${GITEA_SECRET_KEY}
+
   healthcheck:
     test: ["CMD", "curl", "-f", "http://localhost:3000"]
     interval: 30s

docs/Containers/Gitea.md

@@ -106,7 +106,51 @@ Environment variables need to be set in several stages:
 
 	See [Gitea Server](https://docs.gitea.com/next/administration/config-cheat-sheet#server-server) for more information.
 
-### database root password  { #rootpw }
+4. By default, Gitea expects to communicate using the HTTP protocol. If you want Gitea to switch to HTTPS, you need to do the following:
+
+	- Generate a self-signed certificate:
+
+		``` console
+		$ docker exec gitea gitea cert --host «hostname»
+		```
+		
+		where `«hostname»` should be the first part of the fully-qualified domain name that the **user** uses to reach the Gitea service. Examples:
+		
+		* `gitea.my.domain.com` = `gitea`
+		* `host.my.domain.com` = `host`
+
+	- Uncomment the following environment variables in the service definition:
+
+		``` yaml
+		environment:
+		...
+		# - GITEA__server__KEY_FILE=/data/git/key.pem
+		# - GITEA__server__CERT_FILE=/data/git/cert.pem
+		```
+		
+		These variables tell Gitea where to find the X.509 certificate and matching private key that were generated in the first step.
+		
+	- Tell Gitea to enable HTTPS:
+
+		``` console
+		$ echo "GITEA_WEB_PROTOCOL=https" >>~/IOTstack/.env
+		```
+		
+	- Recreate the container:
+
+		``` console
+		$ cd ~/IOTstack
+		$ docker compose up -d gitea
+		```
+		
+	If everything has gone according to plan, Gitea will be expecting HTTPS traffic and will perform SSL authentication using the key and certificate generated in the first step.
+	
+	Notes:
+	
+	* The certificate has a one-year lifetime. It can be regenerated at any time by re-running the command provided earlier.
+	* Gitea also supports LetsEncrypt. See [using ACME with Let's Encrypt](https://docs.gitea.com/administration/https-setup#using-acme-default-lets-encrypt).
+
+## database root password  { #rootpw }
 
 At the time of writing (April 2025), the MariaDB instance was not respecting the environment variable being used to pass the root password into the container.
 
@@ -215,3 +259,95 @@ $ docker compose up -d gitea_db
 $ docker system prune -f
 ```
 
+## migrating existing repositories
+
+The simplest approach to migrating an existing repository into Gitea is:
+
+1. Start with an existing clone of the repository you want to migrate;
+2. Convert the existing clone to a "bare" repository;
+3. Copy the "bare" repository into Gitea's persistent store; and
+4. Use the Gitea GUI to adopt it.
+
+### existing clone
+
+Let's assume you have an existing clone of a repository named "my-project" at the path:
+
+```
+~/my-repos/my-project
+```
+
+### convert to bare
+
+To convert that existing clone to a "bare" repository:
+
+``` console
+$ mkdir ~/bare
+$ cd ~/bare
+$ git clone --bare ~/my-repos/my-project
+```
+
+The result will be a folder at the path:
+
+```
+~/bare/my-project.git
+```
+
+Note:
+
+* If you already have a "bare" repository stored somewhere then the only thing you are likely to need to do is to rename the directory to have the `.git` extension.
+
+The bare clone will probably have inherited the remote URL(s) that were associated with the original cloning process. Those don't actually cause any harm but they can be confusing so it is a good idea to get rid of them:
+
+```
+$ cd my-project.git
+$ git remote -v
+origin	«pathOrURLTo»/my-project (fetch)
+origin	«pathOrURLTo»/my-project (push)
+$ git remote remove origin
+```
+
+This example only had one remote ("origin"). Some projects have multiple remotes (eg "upstream") so keep executing the `git remote remove «remote»` command until all remotes have been removed.
+
+### copy to Gitea's persistent store
+
+Assuming you have been doing all this work on a computer which is **not** where Gitea is running, the next step is to move the `my-project.git` folder onto the host where Gitea is running. How you do that is up to you. For example:
+
+* the `scp -r` command <sup>†</sup>;
+* the `sftp` command plus the `put -r` command <sup>†</sup>;
+* file-sharing protocols such as SAMBA or SSHFS; or
+* "sneaker-net" via a thumb drive.
+
+	> <sup>†</sup> in each case, the `-r` (recursive) is needed to copy the directory and its contents
+
+On the host where Gitea is running, I'm going to assume that the bare repository is at:
+
+```
+~/my-project.git
+```
+
+Move into the Gitea persistent store:
+
+```
+$ cd ~/IOTstack/volumes/gitea/data/git/repositories/«user»/
+```
+
+where `«user»` is your username as known to Gitea.
+
+Move the bare repository into this scope:
+
+```
+$ mv ~/my-project.git .
+```
+
+Note:
+
+* There has been no mention thus far of ownership and permissions. That's because the Gitea container runs as userID 1000. Inside the container, that's the username "git". Outside the container, userID 1000 is the first user defined on the Linux system and is the account that the majority of Linux users login under. You will only have to be concerned about ownership and permissions if you depart from this norm. 
+
+### adopt the repository
+
+Go to the Gitea GUI and login to your account. From the main menu, choose "Settings".
+
+In the left hand panel, click "Repositories". If all has gone well, `my-project` will be present in the list, associated with <kbd>Adopt Files</kbd> and <kbd>Delete</kbd> buttons. Click <kbd>Adopt Files</kbd>, then click <kbd>Yes</kbd> to adopt pre-existing files.
+
+The end result is a private repository. If you want it to be public, click on the name of the newly-adopted repository in the list, then click <kbd>Settings</kbd>. Scroll to the bottom of the page into the "Danger Zone" and click <kbd>Make Public</kbd> followed by <kbd>Yes</kbd>.
+