Zum Hauptinhalt springen
Version: 7.2

OpenCloud on a Raspberry Pi

hinweis

The installation of OpenCloud on a Raspberry Pi is intended for private or non-production use only.
It is not recommended for enterprise or critical environments due to the hardware's limited resources and potential performance constraints.

Hardware requirements​

  • Minimum Raspberry Pi 4B with at least 4 GB RAM connected via LAN or WLAN
  • Micro SD card with at least 32 GB storage space
  • External hard disk or USB stick (optional) for additional storage space

Install operating system​

  • Install the 64-bit version of Raspberry Pi OS
    A very detailed and understandable guide is available at:
    Raspberry Pi Getting Started

  • Create a user account during the installation, for example in the Raspberry Pi Imager. Current versions of Raspberry Pi OS no longer have a default pi user.

  • SSH must be enabled if you want to access the machine remotely.

    This is usually required when your Raspberry Pi is running without a connected keyboard and display.

  • If the Raspberry Pi is to be connected to WLAN, the login data for the WLAN must be entered.

Connecting with SSH​

Start the Raspberry Pi with the SD card and connect via SSH.
The IP for this can be viewed in your router.

find ip from raspberry-pi in router

Establish connection via SSH​

ssh YOUR-USERNAME@YOUR-IP

Replace YOUR-USERNAME with the user you created during the installation.

After the first login, you should change the password for security reasons:

passwd

Installing Docker and Docker Compose​

Detailed installation instructions for Docker can be found here:
Install Docker on Raspberry Pi

  • Perform update and upgrade:
sudo apt update && sudo apt upgrade -y
  • Install Docker via script:

The Docker convenience script installs from the stable release channel and is intended for testing and development. For maintained installations, follow the official Docker installation instructions. Check that your Raspberry Pi OS version and architecture are supported.

curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
  • Add current user to the Docker group:
sudo usermod -aG docker ${USER}
  • Check if it's working:
groups ${USER}
Check docker user
  • Reboot the Raspberry Pi:
sudo shutdown -r now

Clone OpenCloud repository​

git clone https://github.com/opencloud-eu/opencloud-compose.git

Start the Docker Compose setup​

cd opencloud-compose

Copy the .env.example file:

cp .env.example .env

Edit the .env file:

nano .env

Activate the minimal OpenCloud setup by un-commenting this line:

COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml

Look for the following line and set here your admin password:

INITIAL_ADMIN_PASSWORD=YourSecurePassword
Using external storage?

If you plan to use an external drive, mount it and configure OC_DATA_DIR as described below before the first OpenCloud startup. Skip the next startup command and complete the external storage instructions first. Start OpenCloud only after setting OC_DATA_DIR.

If you are using the default Docker data volume, start OpenCloud now:

docker compose up -d

Once started, OpenCloud runs locally on your Raspberry Pi. To follow the startup, run docker compose logs -f opencloud.

Access OpenCloud in your local network​

By default, OpenCloud is available at https://cloud.opencloud.test. To open it from a computer in your local network, add the following line to the hosts file of that computer. Replace YOUR-IP with the IP address of your Raspberry Pi:

YOUR-IP cloud.opencloud.test

The hosts file is located at /etc/hosts on Linux and macOS and at C:\Windows\System32\drivers\etc\hosts on Windows.

Then open https://cloud.opencloud.test in your browser and sign in with the user admin and the password you set as INITIAL_ADMIN_PASSWORD. Your browser displays a certificate warning, because OpenCloud uses a self-signed certificate for this domain.

We will describe how to mount an external disk or USB stick and make OpenCloud available outside the local network using No-IP.

Mount external hard disk or USB stick​

Find your external drive​

lsblk
find the external hd

Format the drive to ext4​

Data loss warning

Formatting a partition permanently erases its existing data. Back up any important files before proceeding.

The device path /dev/sda1 below is only an example. Use lsblk -f to identify your external drive and verify the correct partition, size, and mount points before formatting. Do not format a partition containing data you want to keep.

sudo mkfs.ext4 /dev/sda1 -L DATA
format drive

Add fstab entry for auto-mounting​

Open fstab:

sudo nano /etc/fstab

Add this line:

LABEL=DATA /mnt/data ext4 defaults,nofail 0 2

The nofail option ensures that the Raspberry Pi still starts if the external drive is not connected.

Create the mount point​

sudo mkdir -p /mnt/data

Mount the drive​

sudo mount -a

If an error occurs:

error mounting

Run:

sudo systemctl daemon-reload

And try mounting again.

Verify the mount and set permissions​

Before changing ownership, verify that the external filesystem is mounted at /mnt/data:

findmnt --mountpoint /mnt/data

If the expected filesystem is not mounted, correct the mount configuration before proceeding.

For a new, empty data filesystem, set ownership of its root directory:

sudo chown 1000:1000 /mnt/data

Verify that UID and GID 1000:1000 are appropriate for your deployment. Do not recursively change ownership of an existing drive without checking its contents and required permissions.

Mount external storage in Docker​

Existing installations

Changing OC_DATA_DIR does not migrate existing data from the previous Docker volume. The data directory contains not only files, but also users, shares, and the search index. Before switching storage on an existing installation, back up your OpenCloud data and configuration and follow a verified migration procedure. Otherwise, existing files, users, and shares may appear missing.

If OpenCloud is already running, stop its Compose services:

docker compose down

Open the .env file:

nano .env

Set the OC_DATA_DIR variable to your mounted storage path, e.g.:

OC_DATA_DIR=/mnt/data
change env for storage

Start OpenCloud with the configured data directory:

docker compose up -d

Make OpenCloud externally available​

Create DynDNS hostname​

Register at No-IP and create a hostname, e.g. opencloud.webhop.me.

noip hostname input

Configure DynDNS in your router​

Use your router’s web interface to:

  • Locate the Dynamic DNS settings
  • Select No-IP as provider
  • Enter your No-IP credentials
  • Use the created hostname (e.g. opencloud.webhop.me)
  • Save and test the settings

More help: No-IP Support

Configure port forwarding​

  1. Ensure your Raspberry Pi always has the same IP address:

    • Either via static IP or DHCP assignment in the router
  2. In your router settings, look for Port Forwarding, NAT, or Port Sharing

  3. Forward the following ports to your Raspberry Pi:

  • TCP Port 80 (HTTP)
  • TCP Port 443 (HTTPS)
portforwarding in router

Update OC_DOMAIN​

SSH into your Pi and update the domain:

cd opencloud-compose
docker compose down
nano .env

Edit the OC_DOMAIN value and set your email address for the Let's Encrypt certificate:

OC_DOMAIN=opencloud.webhop.me
TRAEFIK_ACME_MAIL=your@email.com

Traefik uses this email address to request a valid certificate from Let's Encrypt for your domain.

change the OC_DOMAIN variable

Start OpenCloud again:

docker compose up -d

Now your OpenCloud should be reachable via your URL.

reachable-via-URL