Onedev - ArchWiki

Jump to content
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.

Categories:

- Git web interfaces
- Servers