From ArchWiki

OneDev is an open source git server developed by a single developer written in java. OneDev provides powerful search and navigation, easy to use CI/CD, searching through codebases using regular expression, and integrated Kanban support.

OneDev currently does not provide any publicly available instances to use such as other git servers like Gitlab, thus must be self hosted.

Installation

AUR

Install onedevAUR.

Note: Installing from AUR requires you to manually build the package using Makepkg, this could take a while.

Unofficial repositories

Onedev is currently available on PolarRepo.

Note: It is advised you add Onedev to /etc/pacman.conf under IgnorePkg due to the manual update process, this will prevent pacman from interfering.

Running

Start/enable onedev.service

You will be able to access OneDev to finish installation at http://127.0.0.1:6610

Updating

Onedev relies heavily on the use of Java Service Wrapper, a proprietary JVM wrapper used to distribute Java code with less hassle, however due to this, the update process of the onedev package can not be done automatically and requires manual intervention.

Note: Please ensure that you Stop onedev.service before you continue to prevent corruption of data, or errors during the update.

Firstly, backup /opt/onedev to ensure if the update goes badly we can roll back the data to ensure no data is lost.

Tip: You should already be periodically backing up this directory to prevent data loss in case of server failure

You can backup this directory however you like, however for this example we will back it up in the following format onedev-version.tar.xz, xz compression provides the highest compression ratio with the downside of long compression and decompression times however for backups, it is vital you compress them as much as possible to save disk space.

# tar -cvf onedev-version.tar.xz -R /opt/onedev

This will compress all the data within the onedev directory into a tar archive and compress it using xz. Ensure you replace version with the current version before you update.

Now that you have backed up the data, we can attempt to update Onedev.

Install onedev-newAUR, which is a special package which only contains the latest build, without any of the accompanying files, such as the Onedev user or the systemd service. The package will be used to "patch" the current onedev instance, migrating all the data to the new version of Onedev.

Once the package is installed you will need to run the following command as the onedev user, we will use ! to denote a command which has to be run as the Onedev user, this can be done through the following commands:

With Sudo:

# sudo -u onedev command

With OpenDoas:

# doas -u onedev command

You replace command with the following command below:

! /opt/onedev-new/bin/upgrade.sh /opt/onedev
Note: This command will most likely take a long time, as it will be exporting and importing the database entries, the bigger the database the longer this will take.

Once the migration is complete, you can Install onedevAUR, some of the files could be duplicates due to the update.sh script, so to prevent errors ensure to tell Pacman to overwrite these duplicates using --overwrite '*'.

You can now Start onedev.service, if Onedev starts successfully, you can Remove onedev-newAUR to save disk space.

Documentation

Onedev provides in-depth documentation about its features, and how to use all their features using Docusaurus. Those who want to be able to view the documentation offline, or do not want to rely on a publicly hosted documentation (for privacy reasons), follow the guide below.

First, install onedev-docsAUR (also available from PolarRepo to avoid building the package manually), which contains the latest documentation from upstream. Due to the limitation of Docusaurus, in order to view the documentation properly you must use a web server. This can be done by running this Python command:

$ python -m http.server --directory /usr/share/doc/onedev/html

You can view the documentation in your browser at http://localhost:8000.

Configuration

Onedev has very limited configuration due to the majority of the configuration being done through the web interface. The configuration file can be found under /opt/onedev/conf/server.properties.

Default configuration

/opt/onedev/conf/server.properties
# Specify http port to access the server
http_port=6610

# Specify port for embedded ssh server that will enable ssh based services such as 
# git over ssh  
ssh_port=6611

# path to directory containing CA PEM files to be trusted by OneDev. Non-absolute path is 
# considered to be relative to OneDev conf directory  
#trust_certs=trust-certs

# Specify ip address for clustering. Leave empty to detect automatically 
# cluster_ip=

# Specify port for clustering
cluster_port=5701

Reverse proxy

By default, OneDev listens on port 6610 for http connections. In order to securely access OneDev, a reverse proxy should be setup. nginx is recommended over another web server such as Apache HTTP Server as it is faster are more lightweight.

Before configuring a reverse proxy you must have a functional nginx install, see nginx for installation. Find the nginx configuration below, this has been taken from the [OneDev Wiki].

/etc/nginx/sites-enabled/onedev
server {
     listen 443 ssl;

     server_name onedev.example.com;
     ssl_certificate /path/to/your/fullchain;
     ssl_certificate_key /path/to/your/key;
     
     # maximum size of uploaded file. Increase this if your repository is very large
     client_max_body_size 100M; 
     
     location /wicket/websocket {
             proxy_pass http://localhost:6610/wicket/websocket;
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "upgrade";                
     }

     location /~server {
             proxy_pass http://localhost:6610/~server;
             proxy_http_version 1.1;
             proxy_set_header Upgrade $http_upgrade;
             proxy_set_header Connection "upgrade";
     }
     
     location / {
             proxy_pass http://localhost:6610/;
     }
}

Replace the server_name with your domain name.
Replace ssl_certificate with the path to your fullchain file
Replace ssl_certificate_key with the path to your fullchain key

Issuing SSL certificate

For issuing SSL certificates, use Acme.sh as it allows automatic renewal, and is a lot more user friendly than Certbot, however the ACME client you use is up to personal preference.

Firewall

If you are using a firewall such as ufw, you will need to open port 443 to allow traffic to pass through to OneDev:

ufw allow 443

This has to be ran as root, or append doas (if you are using doas) or sudo (if you are using sudo).

Accessing OneDev from your domain

In order to access your OneDev instance using the domain over HTTPS, you need to point your domain towards your server. Add an A record (or AAAA for IPv6 support) with your DNS provider for the server_name specified in your nginx configuration, the A record must point to the IP address of the server running nginx, not the server running OneDev.

Known issues

Updating Onedev package breaks Onedev

Currently the Onedev package does not migrate the data when updating, this is being implemented however due to the use of JSW (Java Service Wrapper), it is difficult to properly implement this within a package format. For more information, see Issue 1.

Troubleshooting

Image can't be read correctly when building onedev-docs

If you get the following error:

[WARNING] The image at "<some location>" can't be read correctly. Please ensure it's a valid image.

Git-lfs never resolved the images from the repository, thus the files are in text form defining the file information which git-lfs was meant to pull, which is why it is not a valid image. This occurs if you have not initialised git-lfs doing the following:

$ git-lfs install

Then rebuild the package and it should work fine.