Building and running OpenCloud on FreeBSD with Apache as reverse proxy

[artanis42]

Hi all,

I would like to share my experiences with building and running OpenCloud on FreeBSD. I am running home servers on FreeBSD 14.3 and wanted to give OpenCloud a try in comparison to Nextcloud. But I wanted to run OpenCloud natively on FreeBSD, not inside a Docker
container. FreeBSD itself already ships with virtualization technologies like jails and bhyve.

A very good starting point is the Bare-Metal installation guide on the homepage.

Building OpenCloud

To build OpenCloud I set up a dedicated virtual machine as a build server running FreeBSD 14.3. You can follow the installation guide and install required packages using pkg install:

• git
• go (must be version 1.24 or higher)
• npm
• bash
• gmake

Also, install and enable corepack as described.

The build itself does not require you to be the root user.

Now, clone the repository, change into the directory and start the build:

gmake clean generate
gmake -C opencloud build

Biggest difference here is to use the gmake command instead of make. At this point the build might report an error. To get more information you can add the -d parameter to the gmake command. It is likely, that the error points to a problem in the GoUtil component of Gookit. Here, sysutil is not able to determine the correct operating system. Fortunately, somebody already added FreeBSD support to GoUtil, so we can download a single file to patch the local build environment:

cd vendor/github.com/gookit/goutil/sysutil
fetch https://raw.githubusercontent.com/gookit/goutil/refs/heads/master/sysutil/sysutil_unix.go

After that, start the build again. This time it should run successfully and you end up with a single binary in the opencloud/bin directory. Move the binary to the desired target directory (in FreeBSD this is usually /usr/local/bin).

Running OpenCloud

Once again, follow the Bare-Metal installation guide to initialize and run OpenCloud. As OpenCloud is built with Docker in mind, please note, that almost all configuration is done using environment variables. So you have to set some variables prior to running OpenCloud, the most important ones being OC_URL, OC_CONFIG_DIR, OC_BASE_DATA_PATH and OC_INSECURE. You can also get rid of the Go memory limit warning by setting AUTOMEMLIMIT_EXPERIMENT=system. In this example, the URL would be https://opencloud.domain.tld.
To start OpenCloud as a service, you can create an rc script in the /usr/local/etc/rc.d directory. I took the rc script from another piece of Go software as blueprint and created a script named opencloud with the following content:

#!/bin/sh

# PROVIDE: opencloud
# REQUIRE: NETWORKING SYSLOG
# KEYWORD: shutdown
#
# Add the following lines to /etc/rc.conf to enable opencloud:
#
#opencloud_enable="YES"

. /etc/rc.subr

name="opencloud"
rcvar="opencloud_enable"

load_rc_config $name

: ${opencloud_user:="www"}
: ${opencloud_enable:="NO"}
: ${opencloud_facility:="daemon"}
: ${opencloud_priority:="info"}

command="/usr/local/bin/${name} server"
procname="/usr/local/bin/${name}"

pidfile="/var/run/${name}.pid"

start_cmd="${name}_start"

opencloud_start() {
        /usr/sbin/daemon -S -l ${opencloud_facility} -s ${opencloud_priority} -T ${name} \
                -u ${opencloud_user} -p ${pidfile} \
		$command
}

run_rc_command "$1"

I also opted to outsource all required environment variables to an environment file named opencloud.env. This stops pollution of the rc script. I put this file into the /usr/local/etc directory. You also have to add the following lines to /etc/rc.conf:

opencloud_enable="YES"
opencloud_env_file="/usr/local/etc/opencloud.env"

Configure OpenCloud to run behind Apache

Apache httpd can be used as proxy to forward requests to OpenCloud. To accomplish this, you need a dedicated subdomain for OpenCloud (here opencloud.domain.tld) and a certificate for secure connections. The key and certificate files must be placed inside the OC_BASE_DATA_PATH/proxy directory. For simplicity name them server.crt and server.key. In Apache, a virtual host must be defined that acts as a reverse proxy. Create a file inside the /usr/local/etc/apache24/extra directory, this will automatically be picked up:

<VirtualHost *:443>
        ServerName opencloud.domain.tld
        SSLProxyEngine on
        ProxyPass / https://localhost:9200/
        ProxyPassReverse / http://localhost:9200/
        ProxyPreserveHost On
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Real-IP "%{REMOTE_ADDR}s"
</VirtualHost>

I hope I covered all steps and did not forget anything important.

It would be great, if FreeBSD would be supported natively one day.

A great thank you to the team behind OpenCloud!

Best regards

[fschade]

thanks for sharing 👍

[Klex167]

Hello everyone,

building under FreeBSD 15.0 RELEASE works wonderfully.
./opencloud init is also no problem, but with ./opencloud server I get the following problems regarding the storage provider:

{"level":"error","error":"unknown edition channel ''","time":"2025-12-24T15:49:30.418391349Z","caller":"/root/opencloud/pkg/version/version.go:55","message":"falling back to dev"}
{"level":"error","service":"storage-users","host.name":"opencloud","protocol":"grpc","error":"unable to register services: rgrpc: grpc service storageprovider could not be started,: tree: unfit storage '/root/.opencloud/storage/users': extended attributes not supported: xattr.Set /root/.opencloud/storage/users/posixfs-xattr-check-102456362 user.posixfs.test: invalid argument","time":"2025-12-24T15:49:31Z","message":"reva server error"}
{"level":"error","service":"storage-users","host.name":"opencloud","protocol":"http","error":"http service dataprovider could not be started,: tree: unfit storage '/root/.opencloud/storage/users': extended attributes not supported: xattr.Set /root/.opencloud/storage/users/posixfs-xattr-check-4177462611 user.posixfs.test: invalid argument","time":"2025-12-24T15:49:31Z","message":"reva server error"}
Error: unable to register services: rgrpc: grpc service storageprovider could not be started,: tree: unfit storage '/root/.opencloud/storage/users': extended attributes not supported: xattr.Set /root/.opencloud/storage/users/posixfs-xattr-check-102456362 user.posixfs.test: invalid argument
Usage:
  storage-users server [flags]

Flags:
  -h, --help   help for server

{"level":"error","service":"opencloud","event":"opencloud: Failed service 'storage-users' (1.000000 failures of 5.000000), restarting: true, error: unable to register services: rgrpc: grpc service storageprovider could not be started,: tree: unfit storage '/root/.opencloud/storage/users': extended attributes not supported: xattr.Set /root/.opencloud/storage/users/posixfs-xattr-check-102456362 user.posixfs.test: invalid argument","service":"storage-users","supervisor":"opencloud","restarting":true,"failures":1,"threshold":5,"error":{},"time":"2025-12-24T15:49:31Z","message":"service terminated"}
{"level":"error","service":"storage-users","host.name":"opencloud","protocol":"http","error":"http service dataprovider could not be started,: tree: unfit storage '/root/.opencloud/storage/users': extended attributes not supported: xattr.Set /root/.opencloud/storage/users/posixfs-xattr-check-2231278076 user.posixfs.test: invalid argument","time":"2025-12-24T15:49:31Z","message":"reva server error"}
panic: runtime error: invalid memory address or nil pointer dereference
[signal SIGSEGV: segmentation violation code=0x1 addr=0x1b0 pc=0x4afaa77]

goroutine 613 [running]:
google.golang.org/grpc.(*Server).stop(0x0, 0x1)
	/root/opencloud/vendor/google.golang.org/grpc/server.go:1929 +0x37
google.golang.org/grpc.(*Server).GracefulStop(...)
	/root/opencloud/vendor/google.golang.org/grpc/server.go:1925
github.com/opencloud-eu/reva/v2/pkg/rgrpc.(*Server).GracefulStop(0x875258420)
	/root/opencloud/vendor/github.com/opencloud-eu/reva/v2/pkg/rgrpc/rgrpc.go:289 +0x25
github.com/opencloud-eu/reva/v2/cmd/revad/runtime.(*server).Stop.func1()
	/root/opencloud/vendor/github.com/opencloud-eu/reva/v2/cmd/revad/runtime/drivenserver.go:109 +0x5c
created by github.com/opencloud-eu/reva/v2/cmd/revad/runtime.(*server).Stop in goroutine 607
	/root/opencloud/vendor/github.com/opencloud-eu/reva/v2/cmd/revad/runtime/drivenserver.go:107 +0x8d

does anyone have an idea how I could solve this?

[micbar]

@aduffeck Maybe the check also needs to be adapted to FreeBSD?

[artanis42]

Hi @Klex167,

may I ask, on what type of filesystem your root‘s home directory (OpenCloud data directory) is located? Is it FreeBSD UFS or is it ZFS? I am running OpenCloud on UFS without any problems regarding extended attributes. But if I try to sync data on to a ZFS filesystem, it gives me errors on those extended attributes starting with „user.“. In your case it has a problem with „user.posixfs.test“. See opencloud-eu/reva#455. Seems, ZFS doesn‘t like that „user“ prefix.

I am curious, if this problem would also arise on a Linux with ZFS filesystem…

Best regards

[Oxyaxion]

Many thanks for sharing this. Off course FreeBSD should be documented and supported by default.

[h-2]

It would be really nice to have this in the FreeBSD ports. Has anyone started working on that?