Onedev

OneDev is an open source git server developed by a single developer written in java, providing powerful search and navigation features, easy to use CI/CD, and integrated Kanban support.

Note: Onedev is a self hosted solution, it does not come with a Software as a Service (SaaS) solution, however onedev has community instances.

Installation

AUR

Install onedev-bin^AUR.

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-new-bin^AUR, 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 onedev-bin^AUR, 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-new-bin^AUR 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-docs^AUR (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.

Removal

Remove onedev-bin^AUR. The following directories persist after removal:

• /opt/onedev/conf/ - Directory containing your onedev configuration
• /opt/onedev/incompatibilities/ - Directory containing a markdown file distributed by upstream for the incompatibilities between versions, this is safe to delete.
• /opt/onedev/logs/ - Logs stored by onedev, during execution, backups and upgrades. These are safe to delete.
• /opt/onedev/sampledb/ - Directory containing the Hyper SQL database used by default, this contains the data stored by onedev, you can delete this if you configured onedev to store the data within an external database (such as PostgreSQL).
• /opt/onedev/site/ - Directory containing all the data for the onedev site, including the generated assets, and the git projects which are stored. Deleting this would cause the loss of all repositories hosted by onedev.
• /opt/onedev/temp - Temporary data, this can be safely deleted.
• /opt/onedev/test - Currently unsure the use of this, only delete if you are willing to risk the onedev data integrity.

If you do not care about any residual data, and want a complete uninstall execute the following command:

# rm -rf /opt/onedev

This will delete the onedev directory and all data within it.

Warning:

• This command can not be reversed, ensure that you are sure you want to delete the data.
• Ensure you got the correct path, running rm -rf as root is dangerous, deleting / would result in the system being destroyed.

Tips and tricks

Community instances

Community instances are hosted by the Onedev community.

Note:

• These instances remain unverified, they are not checked for malicious intent, use at your own risk.
• Different community instances have different specifications and contact methods, ensure you are happy with the specifications of the server(s) running the instance, and are happy with the methods of contact.
• Make sure you trust the chosen instance, you will need to give over your email, this could potentially be abused by a malicious instance.

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.

See also

• Official documentation