RSSAmplifier

fernvenue's Blog · Aug 1, 2024

Gitea Customization

Read inOriginalenesdefrptjazhit
0
Sign in to vote or save

fernvenue's Blog

Compared to GitLab, Gitea is a more lightweight and convenient choice for small teams and personal use. Having used Gitea for a long time and done some additional configurations and customizations on it, besides customizing the homepage and user interface theme, I have also integrated GitHub’s OAuth for authentication. There is also a need to further explain the configuration part related to the privileged port issue mentioned earlier when using Gitea as an example. Here is a brief introduction to these topics.

SSH

In the previous article Using systemd to Bind Applications on Lower Ports, I used Gitea as an example to illustrate how to let Gitea’s systemd service use port 22 without using a privileged user. I’ll briefly add a few details here, if you haven’t read that part, you can refer to the previous article. I used systemd’s AmbientCapabilities to allow Gitea to use port 22, with the corresponding Gitea configuration as follows:

[server]
SSH_DOMAIN = gitea.fernvenue.com
DOMAIN = gitea.fernvenue.com
HTTP_PORT = 3000
ROOT_URL = https://gitea.fernvenue.com/
# DISABLE_SSH = true
START_SSH_SERVER = true
BUILTIN_SSH_SERVER_USER = git
SSH_USER = git
...

This way we can allow Gitea to provide its own SSH service, making it easier and safer for us to git clone via SSH. Additionally, I still use port 3000 for Gitea’s web interface, and I set the ROOT_URL to the actual address I use, which is provided through reverse proxy by Nginx:

server {
    listen 80;
    listen [::]:80;
    server_name gitea.fernvenue.com;
    return 308 https://gitea.fernvenue.com$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name gitea.fernvenue.com;

    ssl_certificate "/etc/nginx/ssl/fernvenue.com.crt";
    ssl_certificate_key "/etc/nginx/ssl/fernvenue.com.key";

    location / {
        client_max_body_size 1024M;
        proxy_redirect off;
        proxy_pass http://[::1]:3000/;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Here in Nginx, I configured a redirect HTTP to HTTPS, supported WebSocket connections, and used the client_max_body_size parameter to increase the allowed size for uploads via HTTP/HTTPS. This significantly improves the user experience.

GitHub OAuth

To add GitHub OAuth as an authentication source for Gitea, you first need to go to GitHub’s Settings - Developer Settings - OAuth Apps and create a new OAuth application. The required information includes:

  • Application name: Gitea
  • Homepage URL: https://gitea.fernvenue.com/
  • Authorization callback URL: https://gitea.fernvenue.com/user/oauth2/GitHub/callback

I filled this out based on my own Gitea setup, so it’s for reference only. I didn’t enable Device Flow by the way. Next, you should receive the Client ID and Client Secret. Take these values to Gitea’s Site Administration - Admin Settings - Identity & Access - Authentication Sources, select to add a new authentication source, and fill in the following information:

  • Authentication Name
  • OAuth2 Provider: GitHub
  • Client ID (Key)
  • Client Secret

The Client ID (Key) and Client Secret are the values provided by GitHub after adding the new OAuth application. Finally, check This Authentication Source is Activated to enable it.

Homepage

The official Gitea documentation provides a brief explanation on Customizing Gitea: Customizing startpage / homepage:

Copy home.tmpl for your version of Gitea from templates to $GITEA_CUSTOM/templates. Edit as you wish. Don’t forget to restart your Gitea to apply the changes.

Customizing the homepage is straightforward. Just create a home.tmpl according to your preferences. Here is the code for the homepage of fernvenue’s Gitea for reference:

{{template "base/head" .}}
<div role="main" aria-label="{{if .IsSigned}}{{.locale.Tr "dashboard"}}{{else}}{{.locale.Tr "home"}}{{end}}" class="page-content home">
	<div class="gt-mb-5 gt-px-5">
		<div class="center">
			<img class="logo" width="220" height="220" src="{{AssetUrlPrefix}}/img/logo.svg" alt="{{.locale.Tr "logo"}}">
			<div class="hero">
				<h1 class="ui icon header title">
					{{AppName}}
				</h1>
				<h2>The one and only one personal Git service for fernvenue.</h2>
			</div>
		</div>
	</div>
	<div class="ui stackable middle very relaxed page grid">
		<div class="eight wide center column">
			<h1 class="hero ui icon header">
				{{svg "octicon-squirrel"}} Code Playground
			</h1>
			<p class="large">
				Code playground to easily write, test and share some interesting snippets, scripts and projects.
			</p>
		</div>
		<div class="eight wide center column">
			<h1 class="hero ui icon header">
				{{svg "octicon-database"}} Cloud Storage
			</h1>
			<p class="large">
				Cloud Storage to sync, save and archive codes from other platforms like GitHub, GitLab and so on.
			</p>
		</div>
	</div>
</div>
{{template "base/footer" .}}

Place it under $GITEA_CUSTOM/templates. I deployed Gitea using packaging/gitea, so I placed it in /var/lib/gitea/custom/templates/home.tmpl. After restarting the service, we should see the new homepage take effect.

By the way, Gitea uses the Octicons icon set, so we can customize the SVG styles on the homepage by referring to the corresponding version’s icons.

Theme

If you refer back to the previously mentioned official documentation, you’ll find the section on Customizing Gitea: Customizing the look of Gitea which explains how to use custom themes. In short, it involves two key steps:

  • Place the theme in $GITEA_CUSTOM/public/assets/css/theme-<theme-name>.css (note the naming format);
  • Add the corresponding <theme-name> in the Gitea configuration file to enable it;

I personally chose the catppuccin/gitea theme mentioned in gitea/awesome-gitea#themes. The README in that repository provides instructions, so I placed it under /var/lib/gitea/custom/public/assets/css/:

~# ls /var/lib/gitea/custom/public/assets/css/
theme-catppuccin-auto.css	      theme-catppuccin-frappe-rosewater.css  theme-catppuccin-latte-mauve.css	   theme-catppuccin-macchiato-flamingo.css   theme-catppuccin-macchiato-sky.css     theme-catppuccin-mocha-pink.css
theme-catppuccin-frappe-blue.css      theme-catppuccin-frappe-sapphire.css   theme-catppuccin-latte-peach.css	   theme-catppuccin-macchiato-green.css      theme-catppuccin-macchiato-teal.css    theme-catppuccin-mocha-red.css
theme-catppuccin-frappe-flamingo.css  theme-catppuccin-frappe-sky.css	     theme-catppuccin-latte-pink.css	   theme-catppuccin-macchiato-lavender.css   theme-catppuccin-macchiato-yellow.css  theme-catppuccin-mocha-rosewater.css
theme-catppuccin-frappe-green.css     theme-catppuccin-frappe-teal.css	     theme-catppuccin-latte-red.css	   theme-catppuccin-macchiato-maroon.css     theme-catppuccin-mocha-blue.css	    theme-catppuccin-mocha-sapphire.css
theme-catppuccin-frappe-lavender.css  theme-catppuccin-frappe-yellow.css     theme-catppuccin-latte-rosewater.css  theme-catppuccin-macchiato-mauve.css      theme-catppuccin-mocha-flamingo.css    theme-catppuccin-mocha-sky.css
theme-catppuccin-frappe-maroon.css    theme-catppuccin-latte-blue.css	     theme-catppuccin-latte-sapphire.css   theme-catppuccin-macchiato-peach.css      theme-catppuccin-mocha-green.css	    theme-catppuccin-mocha-teal.css
theme-catppuccin-frappe-mauve.css     theme-catppuccin-latte-flamingo.css    theme-catppuccin-latte-sky.css	   theme-catppuccin-macchiato-pink.css	     theme-catppuccin-mocha-lavender.css    theme-catppuccin-mocha-yellow.css
theme-catppuccin-frappe-peach.css     theme-catppuccin-latte-green.css	     theme-catppuccin-latte-teal.css	   theme-catppuccin-macchiato-red.css	     theme-catppuccin-mocha-maroon.css
theme-catppuccin-frappe-pink.css      theme-catppuccin-latte-lavender.css    theme-catppuccin-latte-yellow.css	   theme-catppuccin-macchiato-rosewater.css  theme-catppuccin-mocha-mauve.css
theme-catppuccin-frappe-red.css       theme-catppuccin-latte-maroon.css      theme-catppuccin-macchiato-blue.css   theme-catppuccin-macchiato-sapphire.css   theme-catppuccin-mocha-peach.css

The theme-catppuccin-auto.css file was created by choosing the Mocha theme and combining the Light and Dark CSS files. Most browsers implement light and dark mode adaptation using @media (prefers-color-scheme: dark), so the method to combine them is actually quite simple:

...
@media (prefers-color-scheme:dark) {
  :root {
    color-scheme: dark;
    --is-dark-theme: true;
    ...
  }
}

Just place the dark mode styles inside @media (prefers-color-scheme: dark) {...} and concatenate them with the preceding light mode styles. Next, enable these themes in /etc/gitea/app.ini:

...
[ui]
DEFAULT_THEME = catppuccin-auto
THEMES = auto,gitea,arc-green,catppuccin-auto,catppuccin-latte-rosewater,catppuccin-latte-flamingo,catppuccin-latte-pink,catppuccin-latte-mauve,catppuccin-latte-red,catppuccin-latte-maroon,catppuccin-latte-peach,catppuccin-latte-yellow,catppuccin-latte-green,catppuccin-latte-teal,catppuccin-latte-sky,catppuccin-latte-sapphire,catppuccin-latte-blue,catppuccin-latte-lavender,catppuccin-frappe-rosewater,catppuccin-frappe-flamingo,catppuccin-frappe-pink,catppuccin-frappe-mauve,catppuccin-frappe-red,catppuccin-frappe-maroon,catppuccin-frappe-peach,catppuccin-frappe-yellow,catppuccin-frappe-green,catppuccin-frappe-teal,catppuccin-frappe-sky,catppuccin-frappe-sapphire,catppuccin-frappe-blue,catppuccin-frappe-lavender,catppuccin-macchiato-rosewater,catppuccin-macchiato-flamingo,catppuccin-macchiato-pink,catppuccin-macchiato-mauve,catppuccin-macchiato-red,catppuccin-macchiato-maroon,catppuccin-macchiato-peach,catppuccin-macchiato-yellow,catppuccin-macchiato-green,catppuccin-macchiato-teal,catppuccin-macchiato-sky,catppuccin-macchiato-sapphire,catppuccin-macchiato-blue,catppuccin-macchiato-lavender,catppuccin-mocha-rosewater,catppuccin-mocha-flamingo,catppuccin-mocha-pink,catppuccin-mocha-mauve,catppuccin-mocha-red,catppuccin-mocha-maroon,catppuccin-mocha-peach,catppuccin-mocha-yellow,catppuccin-mocha-green,catppuccin-mocha-teal,catppuccin-mocha-sky,catppuccin-mocha-sapphire,catppuccin-mocha-blue,catppuccin-mocha-lavender

Here, I set the adaptive version I just created as the default, while retaining Gitea’s built-in themes: auto, gitea, and arc-green. And now the Gitea should look like this:

image

Links

Read the original on blog.fernvenue.com ↗

Comments

Nothing yet. Say the first thing.

    Sign in to join the conversation.