OpenCloud on a Raspberry Pi
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
piuser. -
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.
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}
- 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
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
Format the drive to ext4
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
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:
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
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
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.
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
-
Ensure your Raspberry Pi always has the same IP address:
- Either via static IP or DHCP assignment in the router
-
In your router settings, look for Port Forwarding, NAT, or Port Sharing
-
Forward the following ports to your Raspberry Pi:
- TCP Port 80 (HTTP)
- TCP Port 443 (HTTPS)
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.
Start OpenCloud again:
docker compose up -d
Now your OpenCloud should be reachable via your URL.
