Migrating Gitea to OmniOS

Share on:

Gitea - Git with a cup of tea - is the fastest, easiest, most hassle-free way of setting up a self-hosted Git service. Gitea includes collaborative features like bug tracking, wikis and code review. One other cool feature is that it has support for two factor authentication.

Gitea was originally forked from the Gogs project in 2016, but has since drastically evolved into the project that it is today.

OmniOS is a perfect platform to host a Gitea Installation. OmniOS regularily keeps up to date with the latest releases from Go & Gitea, making sure you get all the latest features and security updates.

In this post, I will cover migrating from a previous host into a shiny new install of OmniOS. However, this should be applicable to any operating system, with a few minor changes.

Install Necessary Software Packages on OmniOS

On a freshly installed OmniOS host we need to install the packages that we need for Gitea.

Below, I use the most recent stable versions of these packages at the time of this post, however these packages may have had new major version releases since. You can check for the latest versions, with the pkg list command, using the -n flag as such:

1pbd@omnios:~$ pkg list -n |grep nginx                                           
2ooce/server/nginx (extra.omnios)                  1.19.4-151036.0            --- 
3ooce/server/nginx-118 (extra.omnios)              1.18.0-151036.0            --- 
4ooce/server/nginx-common (extra.omnios)           1.0.0-151036.0             --- 

As you see here, Nginx 1.19 is available and could have been used. Also shortly after this post was published, Go 1.16 was released, and this may be preferable to use, rather than Go 1.15.

When we have found the latest packages we want to install, complete as follows:

1pbd@omnios:~$ sudo pkg install git gitea go-115 nginx-118 database/postgresql-12

Preparing PostgreSQL for Gitea

Under OmniOS, PostgreSQL needs to be manually initialised after installation, before the service can be started. This is simple enough and done like this:

 1pbd@omnios:~$ sudo  su - postgres
 2postgres@omnios:~$ /opt/ooce/pgsql-12/bin/pg_ctl -D pgsql-12 initdb
 3The files belonging to this database system will be owned by user "postgres".             
 4This user must also own the server process.                                               
 6The database cluster will be initialized with locale "en_GB.UTF-8".                       
 7The default database encoding has accordingly been set to "UTF8".                         
 8The default text search configuration will be set to "english".                           
10Data page checksums are disabled.                                                         
12fixing permissions on existing directory pgsql-12 ... ok                                  
13creating subdirectories ... ok                                                            
14selecting dynamic shared memory implementation ... posix                                  
15selecting default max_connections ... 100                                                 
16selecting default shared_buffers ... 128MB                                                
17selecting default time zone ... Europe/Warsaw                                             
18creating configuration files ... ok                                                       
19running bootstrap script ... ok                                                           
20performing post-bootstrap initialization ... ok                                           
21syncing data to disk ... ok                                                               
23initdb: warning: enabling "trust" authentication for local connections                    
24You can change this by editing pg_hba.conf or using the option -A, or                     
25--auth-local and --auth-host, the next time you run initdb.                               
27Success. You can now start the database server using:                                     
29    /opt/ooce/pgsql-12/bin/pg_ctl -D pgsql-12 -l logfile start                            
31postgres@omnios:~$ exit                       
32pbd@omnios:~$ sudo svcadm enable postgresql12 

Now the postgresql112 service has been started. Tada!

If you encountered any problems, running svcs -xv postgresql12 is a good place to start.

Setting up the Gitea User & Database in PostgreSQL

Next, we want to create the same database that we had on the previous Gitea host as we will be restoring a database dump into this database shortly.

We need to do this using the postgres user, to create the gitea database and gitea user.

 1pbd@omnios:~$ sudo su - postgres
 2postgres@omnios:~$ psql
 3psql (12.2)
 4Type "help" for help.
 6postgres=# create user gitea WITH PASSWORD 'secret';
 8postgres=# create database gitea;
10postgres=# grant ALL on DATABASE gitea to gitea;
12postgres=# \q
13postgres@omnios:~$ exit

That takes care of prepping the new OmniOS host and its PostgreSQL database.

Migrating Gitea Data to the New OmniOS Host

From the previous Gitea host we need to transfer the database data and the application data. This can be achieved with pg_dump tool and the standard scp command.

Create a Dump of the Previous Gitea Database

Back on the previous Gitea host, we need to transfer all the database data. This is done as follows with the pg_dump tool and then we transfer the gitea_20201123.dump to the new OmniOS host via scp.

1pbd@previous-gitea-host:~$ sudo su - postgres
2postgres@previous-gitea-host:~$ pg_dump gitea > gitea_20201123.dump

When switching into the postgres user, you should be placed into the working directory for PostgreSQL which should allow for the use of the listed pg_dump command. If you encounter any problems with this command, check out the pg_dump man page.

Assuming all went well, scp the dumpfile to the new OmniOS host.

1postgres@previous-gitea-host:~$ scp gitea_20201123.dump root@omnios:/var/opt/ooce/pgsql/

Note: If you can directly log in as root, via ssh/scp, it is a good idea to only allow this with ssh keys, by using the directive PermitRootLogin without-password in /etc/ssh/sshd_config.

Importing a Database Dump into PostgreSQL

On the new OmniOS host import the dumpfile:

1pbd@omnios:~$ sudo su - postgres
2postgres@omnios:~$ psql gitea < gitea_20201123.dump

That takes care of importing all the SQL data into PostgreSQL.

Copy the Gitea Application Data to the new OmniOS host

The database dump only copies the SQL data that gitea stores via PostgreSQL and does not copy the Gitea Application Data (including the Git Repositories), which is also needed to migrate the system. This associated data, including the repositories are stored int the APP_DATA_PATH directory. APP_DATA_PATH is defined in app.ini.

Before copying the previous data to the new host, move the current APP_DATA_PATH directory to something like: APP_DATA_PATH.orig. After this, from the previous Gitea host, the data can be transfered via scp as follows:

1root@previous-gitea-host:~# scp -r .../path/to/gitea/data omnios:/var/opt/ooce/gitea/data

Once these have been received on the new host, change the permissions of the APP_DATA_PATH directory:

1pbd@omnios:~$ sudo chown -R gitea:gitea /var/opt/ooce/gitea/data

The directories and user for Gitea should be available, having been created when instaling the Gitea package.

Now that all the necessary data has been transferred and is in the correct locations, we move onto the configuration of Gitea.

Gitea Configuration

In a migration situation, you should have a working app.ini file for the configuration of Gitea. It is just a matter of copying this app.ini file in place to the new location: /etc/opt/ooce/gitea/app.ini.

I have always run Gitea as a Unix Socket, therefore, the server section, is configured as follows:

 2PROTOCOL         = unix                                                                
 3HTTP_ADDR        = /var/opt/ooce/gitea/gitea.sock                                      
 4DISABLE_SSH      = false                                                               
 5SSH_DOMAIN       = gitea.int.pbdigital.org                                             
 6DOMAIN           = gitea.int.pbdigital.org                                             
 7HTTP_PORT        =
 8ROOT_URL         = https://gitea.int.pbdigital.org/                                    
 9SSH_PORT         = 22                                                                  
10LFS_START_SERVER = true                                                                
11LFS_CONTENT_PATH = /var/opt/ooce/gitea/data/lfs                                        
12LFS_JWT_SECRET   = iGLIKYmwU-not-really-my-secret-xwqr9aaEz1KH
13OFFLINE_MODE     = false                                                               

Should you need to make some tweaks to this on the new host, consult the app.example.ini file.

Configure Nginx for Gitea

If you were hosting Gitea on Nginx before, it is a matter of copying your nginx.conf file to /etc/opt/ooce/nginx-1.18/nginx.conf and change the location of some files. The bare minimum I have needed to make, is to have Nginx point to the gitea.sock, to proxy the Gitea service:

 1    server {                                                                             
 3        listen                  443 ssl;                                                 
 4        ssl_certificate         /etc/pki/tls/certs/gitea.int.pbdigital.org.pem;   
 5        ssl_certificate_key     /etc/pki/tls/private/gitea.int.pbdigital.org.key;        
 6        server_name             gitea.int.pbdigital.org;                                 
 8        location / {                                                                     
 9            proxy_pass http://unix:/var/opt/ooce/gitea/gitea.sock;                       
10        }                                                                                
12    }                                                                                    

I will not explain details of Nginx & TLS Certificates here. If you are not familiar with this, the official documentation is a good place to start.

Start Gitea

That should be all the configuration that is needed. Go ahead and enable both Nginx & Gitea to again provide the service on the new OmniOS host.

1# svcadm enable gitea
2# svcadm enable nginx

Testing the installation

If you have updated your DNS Records to point to the new OmniOS host, you should now be able to access Gitea at the same URL and everything should be as it was previously!

One last thing...

When you push code to your established repositories on your new system, the Git Hooks will fail and these need to be updated to look something like this:

1#!/usr/bin/env bash
2"/opt/ooce/gitea/bin/gitea" hook --config='/etc/opt/ooce/gitea/app.ini' pre-receive

Various hooks, will live under the APP_DATA_PATH/gitea-repos/user/repo.git/hooks/*.d/ directories.

Note: I would like to make a mention about memory. Gitea is very fond of memory and I reccomend running at least 2GB for your OmniOS host.