Gitea Server

Step-by-step deployment instructions for Gitea on Fly.io

Try it: gitea-server.fly.dev

What?

This is a step-by-step guide for recreating our server. If you find it useful, please ⭐

How?

0. Prerequisites

a. Fly CLI installed: https://fly.io/docs/flyctl/
b. Fly account + authenticated on your localhost: https://fly.io/docs/flyctl/auth-signup/
c. Basic understanding of deployment.

1. Create a Fly App

Create a Fly.io App for the Gitea Server (but don't deploy it yet!):

flyctl launch --name gitea-server --image gitea/gitea --org gitea --no-deploy

That will generate a fly.toml file.

2. Create a Volume for Data Storage

Gitea will store git repo files/data on a persistent storage volume. Create it with the following command:

flyctl volumes create gitea_data --size 1 --app gitea-server

3. Update the fly.toml File

The file created by the flyctl CLI will be the default: fly.toml@4494a659 Sadly that's not enough to run Gitea.

The file needs to look more like this:

# fly.toml file generated for gitea-server on 2022-05-14T15:27:31+01:00
app = "gitea-server"

kill_timeout = 5

[build]
  image = "gitea/gitea:latest" # latest is the most recent stable release

[env]
  GITEA__database__DB_TYPE="sqlite3"
  GITEA__database__PATH="/data/gitea/gitea.db"
  GITEA__server__DOMAIN="gitea-server.fly.dev"
  GITEA__server__SSH_DOMAIN="gitea-server.fly.dev"
  GITEA__server__ROOT_URL="https://gitea-server.fly.dev"
  GITEA__server__REDIRECT_OTHER_PORT="true" # listen on port 80, and redirect to "ROOT_URL"
  GITEA__security__INSTALL_LOCK="true" # Don't show installer
  # GITEA__service__DISABLE_REGISTRATION="true" # TODO: uncomment once you have created your first user

# persist data
[[mounts]]
  destination = "/data"
  source = "gitea_data"

# ssh traffic
[[services]]
  internal_port = 22
  protocol = "tcp"
  [[services.ports]]
    port = 22

# for http->https redirect
[[services]]
  internal_port = 80
  protocol = "tcp"

  [[services.ports]]
    handlers = ["http"]
    port = 80

# https traffic
[[services]]
  internal_port = 3000
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

See: commits/54d77542 for the changes made.

4. Deploy!

Once you have saved the fly.toml file, deploy it with the following command:

LOG_LEVEL=debug fly deploy --verbose

5. Configure

Visit your newly deployed instance and configure it as desired: https://gitea-server.fly.dev

If you need to manually configure anything, the gitea configuration file is located at /data/gitea/conf/app.ini on the gitea-server Fly app.

Note: make a backup of your file before you make any changes!!

6. Add SSH Key

Add your public ssh key: https://gitea-server.fly.dev/user/settings/keys

e.g:

6.1 Update the .ssh/authorized_keys file

Once you've added your ssh key to your user on the Gitea server, Update the .ssh/authorized_keys file by visiting: https://gitea-server.fly.dev/admin

You should see the following message confirming the request is being executed:

6.2 Test the ssh Connection

In your terminal run the following command:

ssh -T [email protected]

You should see output similar to the following:

Hi there, nelsonic!
You've successfully authenticated with the key named MBP 2022,
but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.

Create a basic repo, e.g: https://gitea-server.fly.dev/myorg/public-repo

clone it to your localhost:

git clone [email protected]:myorg/public-repo.git

Make a change to one of the files. Then git add . && git commit -m 'file updated' && git push

git push (SSH) works as expected:

https://gitea-server.fly.dev/myorg/public-repo

Now that you've confirmed you can access a git repo hosted on gitea server via your terminal you can already use your server as fully fledged GitHub backup or even replacement! But there's more to explore!

7. Create Access Token (API Key)

Visit: https://gitea-server.fly.dev/user/settings/applications and create a new Access Tokens.

e.g:

Once you have the access token, you can test it by running a cURL command to retrieve repo info:

 curl 'https://gogs-server.fly.dev/api/v1/repos/myorg/public-repo?token=youraccesstokenhere'

Response:

{
  "id": 3,
  "owner": {
    "id": 3,
    "login": "myorg",
    "full_name": "",
    "email": "",
    "avatar_url": "https://gitea-server.fly.dev/avatars/b665280652d01c4679777afd9861170c",
    "language": "",
    "is_admin": false,
    "last_login": "0001-01-01T00:00:00Z",
    "created": "2022-05-15T21:21:42Z",
    "restricted": false,
    "active": false,
    "prohibit_login": false,
    "location": "",
    "website": "",
    "description": "",
    "visibility": "public",
    "followers_count": 0,
    "following_count": 0,
    "starred_repos_count": 0,
    "username": "myorg"
  },
  "name": "public-repo",
  "full_name": "myorg/public-repo",
  "description": "",
  "empty": false,
  "private": false,
  "fork": false,
  "template": false,
  "parent": null,
  "mirror": false,
  "size": 104,
  "html_url": "https://gitea-server.fly.dev/myorg/public-repo",
  "ssh_url": "[email protected]:myorg/public-repo.git",
  "clone_url": "https://gitea-server.fly.dev/myorg/public-repo.git",
  "original_url": "",
  "website": "",
  "stars_count": 0,
  "forks_count": 0,
  "watchers_count": 1,
  "open_issues_count": 0,
  "open_pr_counter": 0,
  "release_counter": 0,
  "default_branch": "master",
  "archived": false,
  "created_at": "2022-05-15T21:40:54Z",
  "updated_at": "2022-05-15T21:40:57Z",
  "permissions": {
    "admin": true,
    "push": true,
    "pull": true
  },
  "has_issues": true
}

Note: this API response is truncated for brevity, For the complete API docs, see: https://try.gitea.io/api/swagger#/repository

Questions?

It wasn't all plain sailing for us when we first tried to setup our gitea-server. We wrote this guide so that others wouldn't suffer our pain.

If you get stuck in your deployment quest, feel free to reach out by opening an issue: gitea-server/issues

Recommended Reading

• Running Gitea on fly.io: https://blog.gitea.io/2022/04/running-gitea-on-fly.io/ recently written/published by @techknowlogick a core contributor to Gitea.
• Gitea Configuration Cheat Sheet: https://docs.gitea.io/en-us/config-cheat-sheet/