Difference between revisions of "Gitea"

From Organic Design wiki
m
(Enabling OIDC)
 
(14 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
{{stub}}
 
{{stub}}
  
We used the default [https://docs.gitea.io/en-us/install-with-docker/ Docker installation] which was very straight forward. The only change to the default ''docker-compose.yml'' we made was to change the external ports to 333 since we already have [[Mastodon]] using port 3000. The HTTP port is also served on localhost only since it will be accessed via proxy only.
+
== Installation ==
 +
We used the default [https://docs.gitea.io/en-us/install-with-docker/ Docker installation] which was very straight forward. The only change to the default ''docker-compose.yml'' we made was to change the external HTTP port of 3000 to an '''internal on 333''' since we already have [[Mastodon]] using port 3000, and we configure [[Nginx]] as a reverse proxy so that the Gitea site is accessible via HTTPS on 443. Their default configuration uses 3000 for the HTTP port and 222 for the SSH port which we have kept as-is.
 
<source lang="yaml">
 
<source lang="yaml">
 
version: "2"
 
version: "2"
Line 25: Line 26:
 
</source>
 
</source>
  
 +
After you are able to access the site online, you can then go through the initial user registration, which asks a bunch of admin question, for us we couldn't set anything, except the database which needed to be set to ''SQLite3''. The web UI configuration page is currently read-only and settings are configured in the ''gitea/gitea/conf/app.ini'' file (if you used the default volumes setup). We made the following changes. The '''SSH_PORT''' is important if you're using a non-standard port because without it the SSH clone option will be incorrect.
 +
<source>
 +
APP_NAME            = Organic Design Gitea
 +
[server]
 +
SSH_DOMAIN          = code.organicdesign.nz
 +
ROOT_URL            = https://code.organicdesign.nz
 +
SSH_PORT            = 222
 +
SSH_LISTEN_PORT      = 22
 +
DOMAIN              = code.organicdesign.nz
 +
[service]
 +
DISABLE_REGISTRATION = true
 +
ENABLE_NOTIFY_MAIL  = true
 +
[mailer]
 +
ENABLED              = true
 +
MAILER_TYPE          = sendmail
 +
FROM                = gitea@organicdesign.nz
 +
</source>
  
== Nginx reverse proxy ==
+
=== Nginx reverse proxy ===
Setting up Nginx as a reverse proxy server means that you can use a normal default port and redirect requests to the docker service internally. For us the site runs as HTTPS publicly which is done with a simple virtual host container and all our existing [[SSL]] set up that's already in place for all the sites. The reverse proxy the redirects requests to Gitea internally unencrypted so we don't need to bother with any SSL or certificate configuration there.
+
Setting up [[Nginx]] as a reverse proxy server means that you can access the site via HTTPS on the usual port 443, and redirect the requests to the docker service internally over plain HTTP to port 333. This is done with a simple virtual host container and all our existing [[SSL]] set up that's already in place for all the sites. The reverse proxy the redirects requests to Gitea internally unencrypted so we don't need to bother with any SSL or certificate configuration there.
 
<source lang="nginx">
 
<source lang="nginx">
 
server {
 
server {
Line 35: Line 53:
 
include /var/www/work/nginx.ssl.conf;
 
include /var/www/work/nginx.ssl.conf;
 
location / {
 
location / {
proxy_pass http://localhost:3000;
+
proxy_pass {!http!}://localhost:{!333!};
 
}
 
}
 
}
 
}
 +
</source>
 +
 +
== Pushing an existing repository from the command line ==
 +
This is not over HTTP because pushing an entire repo and its history is a lot of data that will likely not be accepted by the reverse proxy, so SSH will need to be used. We can update the remote origin URL of our existing repo and insert out non-standard SSH port and then push it as in the following example:
 +
<source lang="bash">
 +
git remote set-url origin ssh://git@code.organicdesign.nz:{!222!}/organicdesign/work.git
 +
git push -u origin master
 +
</source>
 +
 +
== Automatically updating a repo with webhooks ==
 +
We like to have some repos on the server that are automatically updated when anything is changed. We do this by executing a ''git pull'' as root as shown in our [[Git]] article. The [https://docs.gitea.io/en-us/webhooks/ Gitea webhooks documentation] has a sample PHP script that receives the webhook post from Gitea which works perfectly. The only change is that we remove the '''true''' argument from the ''json_decode'' so that it's not an associative array, and then add the following to perform the pull on the correct repo in ''/var/www''.
 +
<source lang="php">
 +
$decoded = json_decode( $payload );
 +
$repo = $decoded->repository->name;
 +
exec( "cd /var/www/$repo && sudo git pull --no-edit" );
 +
</source>
 +
*'''Note1:''' see the webhooks section of the [[Git]] article for details about allowing the ''git pull'' to be performed as root.
 +
*'''Note2:''' the repo being updated should be using SSH (using the clone URL format shown above) to avoid authentication trouble.
 +
 +
== Enabling OIDC ==
 +
This is easiest done through the UI on the browser under settings -> authentication sources.
 +
 +
 +
You can add them through the commandline like this:
 +
<source lang="bash">
 +
sudo docker exec -u git -it gitea-docker_server_1 bash -c "gitea admin auth add-oauth --provider openid-connect--name <NAME> --key <CLIENT ID> --secret <CLIENT SECRET> --auto-discover-url https://<DOMAIN>/.well-known/openid-configuration"
 +
</source>
 +
 +
== Backup ==
 +
Backing up can be done with the following command as shown in [https://docs.gitea.io/en-us/backup-and-restore/ the docs], but this results in a zip file inside the container that then needs to be moved into the volume as root.
 +
<source lang="bash">
 +
docker exec -u git -it -w /tmp $(docker ps -qf "name=gitea-docker_server_1") bash -c '/app/gitea/gitea dump'
 +
docker exec -u root -it $(docker ps -qf "name=gitea-docker_server_1") sh -c 'mv /tmp/gitea-dump-*.zip /data'
 +
</source>
 +
 +
== Upgrade ==
 +
Simply upgrade the container and start a new instance:
 +
<source lang="bash">
 +
docker-compose pull
 +
docker-compose up -d
 
</source>
 
</source>
  
 
== See also ==
 
== See also ==
 +
*[https://docs.gitea.io/en-us/config-cheat-sheet/ Config cheatsheet]
 
*[[Git]]
 
*[[Git]]
 
[[Category:Libre software]]
 
[[Category:Libre software]]

Latest revision as of 22:16, 13 January 2022

Cone.png This article or section is a stub. Stubs are articles that have not yet received substantial attention from the authors. They are short or insufficient pieces of information and require additions to further increase the article's usefulness. The project values stubs as useful first steps toward complete articles.


Installation

We used the default Docker installation which was very straight forward. The only change to the default docker-compose.yml we made was to change the external HTTP port of 3000 to an internal on 333 since we already have Mastodon using port 3000, and we configure Nginx as a reverse proxy so that the Gitea site is accessible via HTTPS on 443. Their default configuration uses 3000 for the HTTP port and 222 for the SSH port which we have kept as-is.

version: "2"
networks:
  gitea:
    external: false
services:
  server:
    image: gitea/gitea:latest
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - gitea
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:333:3000"
      - "222:22"

After you are able to access the site online, you can then go through the initial user registration, which asks a bunch of admin question, for us we couldn't set anything, except the database which needed to be set to SQLite3. The web UI configuration page is currently read-only and settings are configured in the gitea/gitea/conf/app.ini file (if you used the default volumes setup). We made the following changes. The SSH_PORT is important if you're using a non-standard port because without it the SSH clone option will be incorrect.

APP_NAME             = Organic Design Gitea
[server]
SSH_DOMAIN           = code.organicdesign.nz
ROOT_URL             = https://code.organicdesign.nz
SSH_PORT             = 222
SSH_LISTEN_PORT      = 22
DOMAIN               = code.organicdesign.nz
[service]
DISABLE_REGISTRATION = true
ENABLE_NOTIFY_MAIL   = true
[mailer]
ENABLED              = true
MAILER_TYPE          = sendmail
FROM                 = gitea@organicdesign.nz

Nginx reverse proxy

Setting up Nginx as a reverse proxy server means that you can access the site via HTTPS on the usual port 443, and redirect the requests to the docker service internally over plain HTTP to port 333. This is done with a simple virtual host container and all our existing SSL set up that's already in place for all the sites. The reverse proxy the redirects requests to Gitea internally unencrypted so we don't need to bother with any SSL or certificate configuration there.

server {
	listen 443 ssl;
	listen [::]:443 ssl;
	server_name code.organicdesign.nz;
	include /var/www/work/nginx.ssl.conf;
	location / {
		proxy_pass http://localhost:333;
	}
}

Pushing an existing repository from the command line

This is not over HTTP because pushing an entire repo and its history is a lot of data that will likely not be accepted by the reverse proxy, so SSH will need to be used. We can update the remote origin URL of our existing repo and insert out non-standard SSH port and then push it as in the following example:

git remote set-url origin ssh://git@code.organicdesign.nz:222/organicdesign/work.git
git push -u origin master

Automatically updating a repo with webhooks

We like to have some repos on the server that are automatically updated when anything is changed. We do this by executing a git pull as root as shown in our Git article. The Gitea webhooks documentation has a sample PHP script that receives the webhook post from Gitea which works perfectly. The only change is that we remove the true argument from the json_decode so that it's not an associative array, and then add the following to perform the pull on the correct repo in /var/www.

$decoded = json_decode( $payload );
$repo = $decoded->repository->name;
exec( "cd /var/www/$repo && sudo git pull --no-edit" );
  • Note1: see the webhooks section of the Git article for details about allowing the git pull to be performed as root.
  • Note2: the repo being updated should be using SSH (using the clone URL format shown above) to avoid authentication trouble.

Enabling OIDC

This is easiest done through the UI on the browser under settings -> authentication sources.


You can add them through the commandline like this:

sudo docker exec -u git -it gitea-docker_server_1 bash -c "gitea admin auth add-oauth --provider openid-connect--name <NAME> --key <CLIENT ID> --secret <CLIENT SECRET> --auto-discover-url https://<DOMAIN>/.well-known/openid-configuration"

Backup

Backing up can be done with the following command as shown in the docs, but this results in a zip file inside the container that then needs to be moved into the volume as root.

docker exec -u git -it -w /tmp $(docker ps -qf "name=gitea-docker_server_1") bash -c '/app/gitea/gitea dump'
docker exec -u root -it $(docker ps -qf "name=gitea-docker_server_1") sh -c 'mv /tmp/gitea-dump-*.zip /data'

Upgrade

Simply upgrade the container and start a new instance:

docker-compose pull
docker-compose up -d

See also