Skip to main content

Run on Virtual Machine/Bare Metal

To achieve maximum flexibility, you may run OneDev on virtual machine or bare metal machine.

Resource Requirement

OneDev can run happily on a 2 core 2GB box. For personal use, 1 core 1GB box also works. In this case, you will need to edit <OneDev dir>/conf/wrapper.conf to comment out property and uncomment


  1. Make sure your system has Java 11 or higher installed and available in system path.

    • On ArchLinux, also make sure to run below commands to install required fonts:

        sudo pacman -S fontconfig ttf-dejavu
  2. Make sure your system has git 2.11.1 or higher installed and available in system path.

  3. On Linux and Mac, make sure your system has curl installed and available in system path.

  4. Download or onedev-latest.tar.gz

  5. Extract downloaded file into selected installation directory. Make sure current user has full permissions to the directory and all its sub directories.

  6. Open a command prompt, change to the installation directory, and run command bin\server.bat console (on Windows) or bin/ console (on Unix/Linux/Mac) to start the server.

Run as System Service

On Windows Platform

  1. Make sure OneDev can find the Java binaries:

    1. Add Java to your system path if necessary:
      1. Open Sytem Properties and click on Environment Variables.
        1. Under System Variables, double-click on Path.
        2. Add the path the folder path to the Java binaries (e.g.: 'C:\Program Files\OpenJDK\bin').
    2. Edit file <OneDev dir>\conf\wraper.conf and set the value of property to the absolute path for the Java binaries (e.g.: 'C:\Program Files\OpenJDK\bin').
  2. Open a command prompt with administrator privilege and switch to folder <OneDev dir>\bin.

  3. Edit the file <OneDev dir>\conf\wraper.conf, set the values of the properties wrapper.ntservice.account and wrapper.ntservice.password accordingly. Please ensure that the account running the service has full permissions to OneDev directory and all its subdirectories.


    If account is not specified, the service will run under the SYSTEM account. This is the equivalent of running as root in Linux or MacOS. It is highly recommended to run the service as a specific user.

  4. Run command server.bat install. A Windows service with name OneDev will be installed.

  5. To uninstall the service, run command server.bat remove from the same folder with administrator privilege

On Linux and Mac OS X

  1. Edit file <OneDev dir>/conf/wraper.conf to set value of property as path to java command if it does not exist in system path.

  2. By default, the service will run under root user. To run as another user, edit file <OneDev dir>/bin/ and uncomment below line to specify the user. Make sure specified user has full permissions to OneDev directory and all its sub directories:

  3. Run command sudo <OneDev dir>/bin/ install to install the service.

  4. To uninstall the service, run command sudo <OneDev dir>/bin/ remove.

Use External Database

OneDev by default uses the embedded HSQL database for demonstration purpose. For production usage, it is highly recommended to switch to external database for reliability and performance reason. OneDev can work with below databases:

  • MySQL 5.0 or higher
  • SQL Server 2008 or higher
  • PostgreSQL 9.0 or higher
  • MariaDB 5.0 or higher

To switch to use one of above databases, follow below steps (assume OneDev is installed at /opt/onedev - replace /opt/onedev with your Windows path):

  1. Stop OneDev server by running /opt/onedev/bin/server.(sh|bat) stop.
  2. Run command /opt/onedev/bin/backup.(sh|bat) /path/to/backup-file.
  3. Edit file /opt/onedev/conf/ to comment out the HSQLDB section and uncomment the section of your desired external database. Also provide connection details to your database.
  4. Create a blank external database matching connection details of above step.
  5. Run command /opt/onedev/bin/restore.(sh|bat) /path/to/backup-file.
  6. Start OneDev server and check if everything is fine.

Procedure is the same if you want to switch to a different external database than current external database.

Increase Ulimit

If you have many projects, you may encounter the "too many open files" issue on Linux/Mac platform. In this case, please increase ulimit of the user running OneDev process. There are a lot of guides on how to do this, for instance: