Linux installation

WebOne can be started on GNU/Linux servers. It is supporting all distributions that can run .NET 6.0.

The project is providing official packages for Debian/Ubuntu (.deb) and Fedora/CentOS (.rpm) for amd64, armhf and arm64 architectures in release archive.

See also: Windows installation | MacOS X installation.

Common things

WebOne configuration file is placed at /etc/webone.conf or ./webone.conf. By default, WebOne also loads all *.conf files from /etc/webone.conf.d/ directory, overriding any options stored in main file. It is better to store user configuration in /etc/webone.conf.d/, as these files will not be overwritten by software updates.

By default, WebOne runs as systemd service. It can be enabled or disabled using standard systemd commands: sudo systemctl enable webone, sudo systemctl disable webone. Don't forget to restart the service after any configuration file(s) changes (sudo service webone restart), or them will be ignored by running instance.

Also it can be started as regular console application (if the daemon is disabled). To start WebOne simply open it in a Terminal, to stop press Ctrl+C or kill the webone process. Information about command line arguments is in separate article.

By default WebOne is running on TCP Port 8080. If your network is using a firewall, you need to open this port in it. To use an other port, go to configuration file and change Port number in [Server] section. Or run WebOne as $ webone 1234 (for Port 1234). Note that to use ports less than 1024 a root privileges are required.

List of required packages

WebOne runs with Microsoft .NET Runtime 6.0. On amd64 architecture it is dotnet-runtime-6.0 package, available from Ubuntu/Fedora/CentOS or Microsoft repositories. The Runtime is included in ARM packages of WebOne (so this is why the packages are so fat). For file format converting WebOne is using external software:

• image file converting: ImageMagick (convert) Dependency
• audio and video converting: FFmpeg or AVconv Optional
• YouTube video processing: yt-dlp or youtube-dl Optional

Install on Ubuntu, Debian

There are DEB packages for Ubuntu 16.04, 18.04, 20.04, 22.04, 24.04 (Xenial/Bionic/Focal/Jammy/Noble) and Debian 10/11/12 (Buster/Bullseye/Bookworm). They also should work in all actual non-LTS releases of Ubuntu and in forks of these distributions (like Linux Mint, Kali or Astra).

Ubuntu 24.04 and up

Ubuntu 24.04 have all required dependencies in repositories.

1. Connect Ubuntu .NET backports package repository (it contains Microsoft .NET 6.0 Runtime).

   $ sudo add-apt-repository ppa:dotnet/backports
   

2. Download and install WebOne package.

   $ sudo apt update
   $ wget https://github.com/atauenis/webone/releases/download/v0.17.3/webone.0.17.3.linux-amd64.deb
   $ sudo apt install ./webone.0.17.3.linux-amd64.deb
   

   💡 If installation seems to be very huge, install package with --no-install-recommends argument. The ffmpeg and yt-dlp packages are need only for video transcoding and YouTube download support.

Ubuntu 22.04 and up

Ubuntu 22.04, 22.10, 23.04, 23.10 have all required dependencies in repositories.

1. Download and install WebOne package.

   $ sudo apt update
   $ wget https://github.com/atauenis/webone/releases/download/v0.17.3/webone.0.17.3.linux-amd64.deb
   $ sudo apt install ./webone.0.17.3.linux-amd64.deb
   

   💡 If installation seems to be very huge, install package with --no-install-recommends argument. The ffmpeg and yt-dlp packages are need only for video transcoding and YouTube download support.
2. (Optional) Set configuration as you want.

   $ sudo touch /etc/webone.conf.d/my.conf
   $ sudo nano /etc/webone.conf.d/my.conf
   

   The file name my.conf is given as example. It may have any name.
3. Restart the proxy server

   $ sudo service webone restart
   

Ubuntu pre-22.04, Debian and other distributions

1. Download and install .NET Runtime and WebOne:

   $ wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
   $ sudo dpkg -i packages-microsoft-prod.deb
   $ sudo apt update
   $ wget https://github.com/atauenis/webone/releases/download/v0.17.3/webone.0.17.3.linux-amd64.deb
   $ sudo apt install ./webone.0.17.3.linux-amd64.deb
   

   • 💡 If installation seems to be very huge, install WebOne package with --no-install-recommends argument.
   • For other versions of Ubuntu or Debian, change debian/12 to your distribution name and version. WebOne version and architecture (0.17.3&amd64) also may be different.
2. (Optional) Set configuration as you want.

   $ sudo touch /etc/webone.conf.d/my.conf
   $ sudo nano /etc/webone.conf.d/my.conf
   

   The file name my.conf is given as example. It may have any name.
3. Restart the proxy server

   $ sudo service webone restart
   

To disable systemd service, run $ sudo systemctl disable webone. To enable: $ sudo systemctl enable webone; sudo systemctl start webone.

Note: Ubuntu 20.04, Debian 11 are providing yt-dlp package only via focal-backports and bullseye-backports repositories.

Install on Fedora

There are RPM packages for Fedora 33 and newer. They also should work with forks of these distributions (like CentOS 7+, CentOS Stream and Red Hat Enterprise Linux 7+).

1. Add Microsoft repository to your OS:
   • CentOS 8, CentOS Stream 9, Fedora, RHEL: Nothing need, it is included out-of-box.
   • CentOS 7:

     $ sudo rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm
     

2. Install WebOne:

   $ sudo dnf -y install https://github.com/atauenis/webone/releases/download/v0.17.3/webone.0.17.3.linux-amd64.rpm
   

   All dependencies will be installed automatically. Change 0.17.3 version and amd64 architecture to which you want.
3. (Optional) Set configuration as you want.

   $ sudo touch /etc/webone.conf.d/my.conf
   $ sudo nano /etc/webone.conf.d/my.conf
   

   The file name my.conf is given as example. It may have any name.
4. Restart the proxy server daemon.

   $ sudo systemctl restart webone
   

If a removal will be need, uninstall the package and remove /etc/webone.conf and /etc/webone.conf.d/ manually.

To disable systemd service, run $ sudo systemctl disable webone. To enable: $ sudo systemctl enable webone; sudo systemctl start webone.

Install on ARM devices

WebOne is compatible with ARMv6, ARMv7 and ARM64 devices. They include Raspberry Pi, Android devices, some modems/routers and even IoT hardware.

Note that old devices with ARMv6 architecture (such as Raspberry Pi Zero and Raspberry Pi 1st generation) are needs armv6 package instead of armhf.

WebOne .deb packages are intended for actual versions of Debian, Ubuntu, Raspbian, Armbian and similar distributions. And .rpm packages are useful for latest Pidoras.

Raspbian 10 and up

As packages of WebOne for ARM architecture contains .NET Runtime inside, the installation steps are identical to Ubuntu 22.04+. Make sure you're choosing right package architecture: armv6 (older Pies), armhf (32-bit) or arm64 (64-bit).

Install on Android

Because Android OS is based on Linux, it's possible to run WebOne on it. Developer have not tested this, so it's only based on community feedback.

1. Make sure you have a Android 5.0+ Android 7.0+ device with at least 400 MB of free space.
2. Install Termux.
3. Install proot environment:

   pkg update && pkg upgrade
   pkg install proot-distro
   proot-distro install ubuntu
   proot-distro login ubuntu
   

4. Install WebOne:

   apt update && sudo apt upgrade
   apt install wget nano mc imagemagick
   wget https://github.com/atauenis/webone/releases/download/v0.17.3/webone.0.17.3.linux-arm64.deb
   apt install ./webone.0.17.3.linux-arm64.deb
   

5. Start the proxy server:

   webone
   

   • To edit configuration, stop the process by Ctrl+C, then run nano /etc/webone.conf.d/myfile.conf (the *.conf file name may be any), and restart WebOne.

If your Android device does not support Termux's proot, see this: https://github.com/atauenis/webone/discussions/120 .

Install on other distributions

Steps for installing on other distributions are similar to Ubuntu, but it is better to follow Microsoft recommendations:

• https://learn.microsoft.com/en-gb/dotnet/core/install/linux-alpine
• https://learn.microsoft.com/en-gb/dotnet/core/install/linux-rhel
• https://learn.microsoft.com/en-gb/dotnet/core/install/linux-opensuse
• https://learn.microsoft.com/en-gb/dotnet/core/install/linux-sles
• https://learn.microsoft.com/en-gb/dotnet/core/install/linux-snap
• https://learn.microsoft.com/en-gb/dotnet/core/install/linux-scripted-manual

TinyCore Linux build

There is a unofficial build of WebOne for TinyCore Linux. It's a lightweight distribution for low-memory environments (mostly for virtualization). It also can be run inside VirtualBox 5.2 on 32-bit Windows XP if CPU is 64-bit and have VT-X enabled.

• https://rutracker.org/forum/viewtopic.php?t=6293503
• The manual is mostly on Russian. An online translator may be useful.
• However running on 32-bit hosts with EM64T/AMD64 CPU is supported, it is much slower than running on a 64-bit host OS.

Run in Docker

There are community-supported Docker images with WebOne.

• https://github.com/way5/docker-webone - Better
• https://gist.github.com/hb9fxq/312001b0f220f6241a6e63361c3d7914 - Obsolete
• Talk: https://github.com/atauenis/webone/issues/15

Install manually

Some distributions (like Ubuntu 20.04 LTS in first few months after its release) have no official packages for Microsoft .NET Runtime. However, WebOne still can be run on them.

1. First go to .NET Downloads and look for Linux binaries of the .NET Runtime. Then download the tar.gz archive with it.

2. Unpack binaries:

   $ mkdir -p $HOME/dotnet && tar zxf dotnet-runtime-6.0.11-linux-x64.tar.gz -C $HOME/dotnet
   

   Note that the listed version 6.0.11 may be some different than your. Also the architecture may be other than x64 if need.

3. Add to ~/.bashrc these lines:

   $ export DOTNET_ROOT=$HOME/dotnet
   $ export PATH=$PATH:$HOME/dotnet
   

4. Download WebOne binary packages or archives for same-architecture Linux, macOS or Windows.

5. Unpack them manually.

   Hint: On Debian/Ubuntu machines you can unpack DEB package with this command: dpkg -x webone.0.12.3.linux-x64.deb ~/WebOneDeb.

6. Configure and run WebOne:

   $ nano webone.conf
          then
   $ dotnet webone.dll
           or
   $ sudo dotnet webone.dll
   

Steps 3-6 can be used if the .NET Runtime is built from sources even on an unsupported OS (like Linux i386, FreeBSD). The webone.dll file is cross-platform CoreCLR binary which using Microsoft IL pseudo-code.

Included webone.service file can be used as template to start WebOne as systemd service. See systemd manuals about how to add a service.

If WebOne still doesn't run, install .NET dependencies.

Compiling from sources or debug

To build WebOne from sources or debug, install dotnet-sdk-6.0 package. Also you will need dotnet-zip, dotnet-deb, dotnet-rpm tools (installing via .NET SDK CLI or NuGet). ARMv6 package building requires Docker, as custom .NET 8 SDK with ARMv6 compiler is running in it.

Debugging is possible under Visual Studio Code IDE. However it is not so powerful as full Microsoft Visual Studio, but provides some features such as breakpoints. Also, building the project in "Debug" configuration (without -c:Release dotnet argument) gives a build with some extra information in log. It can be useful for debug purposes.

Troubleshooting SSL and TLS

WebOne is using system OpenSSL library to process all TLS/SSL traffic. Some Linux distributions are containing stripped builds of OpenSSL without older cipher support or with a ban of MD5/SHA1 certificates. Read more.

Older WebOne versions

• WebOne 0.9.3 also can be launched on Linux through mono-complete (not mono-runtime) but Mono have some bugs on HTTPS/TLS processing, so it is not usable. This is a reason why I've moved the project from .NET Framework/Mono to .NET Core.
• Linux packages for WebOne 0.10.0 were removed because WebOne used configuration file in installation directory, which is not a good practice in *nix. Version 0.10.1 has fixed this architecture mistake.
• WebOne 0.10.x used WebOne package and executable file name case, and single /etc/WebOne/webone.conf configuration file.
• WebOne <0.10.1 used STDOUT pipe instead of log file. WebOne <0.10.3 hadn't support for systemd service mode.
• Support for ARM64 was introduced in WebOne 0.11.2. ARMv6 is supported since 0.16.2.
• WebOne 0.10.x and 0.11.x used .NET Core 3.1 runtime instead of .NET 6.0, used since version 0.12.
• WebOne 0.9.x - 0.15.x used youtube-dl instead of yt-dlp.