mirror of
https://gitea.com/gitea/docs.git
synced 2026-09-18 03:58:52 +00:00
docs(installation): adding podman quadlet instructions (#536)
I was reading the instructions from Docker, trying to adapt to my podman setup (with Quadlet) and through I could share it, some people might find it useful. Signed-off-by: axel7083 <[email protected]> Co-authored-by: silverwind <[email protected]> Co-authored-by: Lunny Xiao <[email protected]> Co-authored-by: axel7083 <[email protected]> Reviewed-on: https://gitea.com/gitea/docs/pulls/536 Reviewed-by: Lunny Xiao <[email protected]> Reviewed-by: silverwind <[email protected]> Co-authored-by: axel7083 <[email protected]>
This commit is contained in:
axel7083
committed by
silverwind
silverwind
co-authored by
silverwind
Lunny Xiao
axel7083
silverwind
Lunny Xiao
axel7083
parent
77e495f772
commit
f1553bed2f
@@ -0,0 +1,166 @@
|
||||
---
|
||||
date: "2026-09-03T20:00:00+02:00"
|
||||
slug: "install-with-podman-quadlet"
|
||||
sidebar_position: 65
|
||||
aliases:
|
||||
- /en-us/install-with-podman-quadlet
|
||||
---
|
||||
|
||||
# Installation with Podman Quadlet
|
||||
|
||||
Similarly to [Docker](with-docker.md), [Podman](https://podman.io/) can be used to deploy Gitea.
|
||||
|
||||
This reference setup guides users through the setup based on Podman Quadlet.
|
||||
Podman Quadlet is the native integration of Podman through systemd.
|
||||
|
||||
To learn more about Podman Quadlet, see [systemd units using Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html).
|
||||
|
||||
This setup installs the quadlets in `~/.config/containers/systemd/`, the directory for rootless quadlets, and uses the rootless images.
|
||||
If you install them in a rootful directory such as `/etc/containers/systemd/`, use the rootful images instead.
|
||||
|
||||
## Basics
|
||||
|
||||
Since Podman v6.0 a single `gitea.quadlets` file can hold multiple quadlets separated by the `---` delimiter.
|
||||
|
||||
Paste the following content into a file named `gitea.quadlets`
|
||||
|
||||
```ini
|
||||
# FileName=gitea-data
|
||||
[Volume]
|
||||
VolumeName=gitea-data
|
||||
---
|
||||
# FileName=gitea-config
|
||||
[Volume]
|
||||
VolumeName=gitea-config
|
||||
---
|
||||
# FileName=gitea
|
||||
[Container]
|
||||
PublishPort=2222:2222
|
||||
PublishPort=3000:3000
|
||||
Image=docker.gitea.com/gitea:@dockerVersion@-rootless
|
||||
ContainerName=gitea
|
||||
Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
|
||||
Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
|
||||
|
||||
[Service]
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
# Start with the user session
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
You can run the installation command
|
||||
|
||||
```sh
|
||||
$ podman quadlet install ./gitea.quadlets --application=gitea
|
||||
/home/user/.config/containers/systemd/gitea/gitea-data.volume
|
||||
/home/user/.config/containers/systemd/gitea/gitea-config.volume
|
||||
/home/user/.config/containers/systemd/gitea/gitea.container
|
||||
```
|
||||
|
||||
The `--application=gitea` flag allows us to tell podman to group the quadlets together, this can help for managing and organizing the quadlets files.
|
||||
|
||||
You can validate the quadlets are properly installed by looking at the list command
|
||||
|
||||
```sh
|
||||
$ podman quadlet list
|
||||
NAME UNIT NAME PATH ON DISK STATUS APPLICATION POD
|
||||
gitea-config.volume gitea-config-volume.service /home/user/.config/containers/systemd/gitea/gitea-config.volume active/exited gitea
|
||||
gitea-data.volume gitea-data-volume.service /home/user/.config/containers/systemd/gitea/gitea-data.volume active/exited gitea
|
||||
gitea.container gitea.service /home/user/.config/containers/systemd/gitea/gitea.container failed/failed gitea
|
||||
```
|
||||
|
||||
You can start the application by running `systemctl --user start gitea` command.
|
||||
|
||||
`WantedBy=default.target` starts the service when the user session starts.
|
||||
Rootless user services do not run without a session, so to start Gitea at boot, enable lingering for the user with `loginctl enable-linger $USER`.
|
||||
|
||||
## Databases
|
||||
|
||||
### PostgreSQL database
|
||||
|
||||
To start Gitea in combination with a PostgreSQL database, apply these changes to the
|
||||
`gitea.quadlets` file created above.
|
||||
|
||||
To start Gitea with a database, we need to create a network, so the database and Gitea container can communicate.
|
||||
|
||||
```diff
|
||||
# FileName=gitea-data
|
||||
[Volume]
|
||||
VolumeName=gitea-data
|
||||
---
|
||||
# FileName=gitea-config
|
||||
[Volume]
|
||||
VolumeName=gitea-config
|
||||
---
|
||||
+ # FileName=gitea-postgres-data
|
||||
+ [Volume]
|
||||
+ VolumeName=gitea-postgres-data
|
||||
+ ---
|
||||
+ # FileName=gitea
|
||||
+ [Network]
|
||||
+ NetworkName=gitea
|
||||
+ ---
|
||||
+ # FileName=gitea-postgres
|
||||
+ [Container]
|
||||
+ Image=docker.io/library/postgres:18
|
||||
+ ContainerName=gitea-postgres
|
||||
+ Network=gitea.network
|
||||
+ Mount=type=volume,src=gitea-postgres-data.volume,destination=/var/lib/postgresql
|
||||
+ Environment=POSTGRES_USER=gitea
|
||||
+ Environment=POSTGRES_PASSWORD=gitea
|
||||
+ Environment=POSTGRES_DB=gitea
|
||||
+
|
||||
+ [Service]
|
||||
+ Restart=always
|
||||
+
|
||||
+ [Install]
|
||||
+ # Start with the user session
|
||||
+ WantedBy=default.target
|
||||
+ ---
|
||||
# FileName=gitea
|
||||
+ [Unit]
|
||||
+ Requires=gitea-postgres.service
|
||||
+ After=gitea-postgres.service
|
||||
+
|
||||
[Container]
|
||||
PublishPort=2222:2222
|
||||
PublishPort=3000:3000
|
||||
Image=docker.gitea.com/gitea:@dockerVersion@-rootless
|
||||
ContainerName=gitea
|
||||
Mount=type=volume,src=gitea-data.volume,destination=/var/lib/gitea
|
||||
Mount=type=volume,src=gitea-config.volume,destination=/etc/gitea
|
||||
+ Network=gitea.network
|
||||
+ Environment=GITEA__database__DB_TYPE=postgres
|
||||
+ Environment=GITEA__database__HOST=gitea-postgres:5432
|
||||
+ Environment=GITEA__database__NAME=gitea
|
||||
+ Environment=GITEA__database__USER=gitea
|
||||
+ Environment=GITEA__database__PASSWD=gitea
|
||||
|
||||
[Service]
|
||||
Restart=always
|
||||
|
||||
[Install]
|
||||
# Start with the user session
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
## Logs
|
||||
|
||||
As systemd manages the container we can use `journalctl` to access the logs
|
||||
|
||||
```sh
|
||||
$ journalctl --user --follow --unit=gitea.service
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:263:runWeb() [I] Starting Gitea on PID: 2
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:115:showWebStartupMessage() [I] Gitea version: 1.27.3 built with go1.26.7-X:jsonv2 : bindata, timetzdata,
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:116:showWebStartupMessage() [I] * RunMode: prod
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:117:showWebStartupMessage() [I] * AppPath: /usr/local/bin/gitea
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:118:showWebStartupMessage() [I] * WorkPath: /var/lib/gitea
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:119:showWebStartupMessage() [I] * CustomPath: /var/lib/gitea/custom
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:120:showWebStartupMessage() [I] * ConfigFile: /etc/gitea/app.ini
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:121:showWebStartupMessage() [I] Prepare to run install page
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:329:listen() [I] Listen: http://0.0.0.0:3000
|
||||
gitea[5967]: 2026/09/03 14:50:42 cmd/web.go:333:listen() [I] AppURL(ROOT_URL): http://localhost:3000/
|
||||
gitea[5967]: 2026/09/03 14:50:42 modules/graceful/server.go:52:NewServer() [I] Starting new Web server: tcp:0.0.0.0:3000 on PID: 2
|
||||
```
|
||||
Reference in New Issue
Block a user