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
Unofficial repositories
Onedev is currently available on PolarRepo.
/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.
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.
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
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.