Cloudreve 4.19.1 on AWS User Guide

Overview

This guide covers launching and using the Cloudreve 4.19.1 on Ubuntu 24.04 AMI from cloudimg on Amazon EC2. It is one version of the cloudimg file sharing and sync listing on AWS Marketplace; you pick it as the software version when you subscribe and launch.

Cloudreve is an open source self hosted cloud drive written in Go. You upload, organise, preview and share files from a web interface, with folders, search, file versions, a trash bin, photo, video and document views, and share links with optional passwords and expiry. Several people can use one server, each with their own space and quota, organised in groups. Files can also be reached over WebDAV (for desktop sync tools and file managers), and an administrator can add storage policies that keep files on the instance's disk or in S3 compatible object storage.

The cloudimg image locks Cloudreve down:

• HTTPS from the first boot. nginx serves Cloudreve on port 443 with a certificate generated on your instance's first boot. Port 80 redirects to HTTPS, and requests for a host name the instance does not serve are dropped.
• No default login and no open sign up. Cloudreve makes the first account that registers its administrator, and leaves self registration open. On this image, first boot registers the administrator with a random password unique to your instance while the web server is still down (so nobody can register first), switches self registration off, checks that an anonymous registration is refused, and only then publishes the site. The sign in is in /root/cloudreve-credentials.txt (root only).
• Secrets unique to your instance. The image ships with no configuration file, no database and no certificate. First boot writes the session secret, and Cloudreve's own first start creates the database with its token signing key, ID salt and file encryption master key, all generated on your instance.
• Cloudreve stays on localhost. It listens on 127.0.0.1:5212 only, as an unprivileged cloudreve account that can write nothing but its own data directory, and it is blocked at the kernel level from reaching the EC2 instance metadata service. It keeps normal outbound access, for S3 storage policies and e-mail.
• Hardened web front. nginx sets the client address itself (a forged X-Forwarded-For header is ignored), strips cross origin (CORS) headers, keeps query strings (signed download links carry their signature there) out of its access log, rate limits sign in and registration, and refuses cross site requests to the two administrator pages that make Cloudreve contact another server.
• Built from source with current security fixes. cloudimg compiles Cloudreve 4.19.1 from the project's own release tag with the current Go toolchain and patched Go libraries (the upstream release binary is built with an older Go release that has since received many security fixes). The web interface is the project's own build, unchanged. The build is reproducible and its record is on the image.
• Fully patched Ubuntu 24.04 LTS at build time, with unattended security upgrades switched on.

What is on the image: Cloudreve 4.19.1 (/opt/cloudreve/cloudreve, GPL-3.0, community edition), nginx, Ubuntu 24.04 LTS, cloud-init and the AWS Systems Manager agent. The licence, the source location, the exact Go module list and the build record are in /usr/share/doc/cloudimg/cloudreve/.

Default user: ubuntu · Architecture: x86_64 · Recommended instance type: m5.large

Prerequisites

• An AWS account subscribed to the listing, an EC2 key pair and a VPC subnet with a route to the internet.
• A security group that allows TCP 22 (SSH), TCP 443 (the web interface and WebDAV) and TCP 80 (redirects to HTTPS) from your own networks only.

Step 1: Launch the instance

In the AWS Marketplace listing choose Continue to Subscribe, then Continue to Configuration, pick Cloudreve 4.19.1 on Ubuntu 24.04 as the software version and your Region, then Launch through EC2. Choose m5.large, your key pair, a security group as above, and a subnet. The AMI brings an 8 GiB root volume and uploaded files are stored on it (/var/lib/cloudreve/data), so raise the root volume under Configure storage to fit the files you plan to keep, or add an S3 storage policy later (Step 8).

With the AWS CLI (replace the values in angle brackets; this sets the root volume to 100 GiB):

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --block-device-mappings 'DeviceName=/dev/sda1,Ebs={VolumeSize=100,VolumeType=gp3}' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=cloudreve}]'

Step 2: Connect to your instance

ssh -i <your-key.pem> ubuntu@<public-ip>

Step 3: Check the services

First boot generates the certificate, the configuration, the database and the administrator, then publishes the site. It takes about ten seconds:

systemctl is-active cloudreve-firstboot cloudreve nginx

active
active
active

Only SSH (22) and nginx (80, 443) listen on the network. Cloudreve (5212) listens on loopback, and the other two are Ubuntu's local DNS resolver:

sudo ss -lntp | awk 'NR>1 {print $4}' | sort -u

0.0.0.0:22
0.0.0.0:443
0.0.0.0:80
127.0.0.1:5212
127.0.0.53%lo:53
127.0.0.54:53
[::]:22
[::]:443
[::]:80

Cloudreve reports its version on its health endpoint, which needs no sign in:

curl -sk https://127.0.0.1/api/v4/site/ping | python3 -c 'import json,sys; print(json.load(sys.stdin)["data"])'

4.19.1

If nginx serves nothing, first boot has not finished (or failed, in which case the site is never published). Check systemctl status cloudreve-firstboot and journalctl -u cloudreve-firstboot.

Step 4: Get your URL and password

sudo cat /root/cloudreve-credentials.txt

The file is readable by root only and holds the address and this instance's administrator sign in:

# Cloudreve on Ubuntu 24.04 (cloudimg AWS Marketplace image) - this instance's administrator sign-in.
# Generated on this instance at first boot; unique to it and not known to cloudimg or the Cloudreve project.
...
CLOUDREVE_URL=https://ec2-203-0-113-10.compute-1.amazonaws.com/
cloudreve.admin.email=admin@cloudreve.local
cloudreve.admin.password=<CLOUDREVE_ADMIN_PASSWORD>

You can confirm the sign in from the instance itself. The helper signs in through nginx, checks that a wrong password and a new registration are refused, and prints CLOUDREVE_ROUNDTRIP_OK:

sudo /usr/local/sbin/cloudreve-verify.sh | tail -1

CLOUDREVE_ROUNDTRIP_OK

The certificate is self signed until you install your own (Step 9). Before you accept it in the browser, you can compare its SHA-256 fingerprint with the one the browser shows:

sudo openssl x509 -in /etc/ssl/cloudreve/cloudreve.crt -noout -fingerprint -sha256

sha256 Fingerprint=3F:A1:...:7C

Step 5: Sign in

Open the CLOUDREVE_URL address in your browser and accept the certificate once (after comparing the fingerprint). Enter the e-mail address admin@cloudreve.local, choose Next, then enter the password from Step 4.

Change the administrator password now: open Settings (the gear icon at the top right), then Password and security, and set a password of your own. You can also add a passkey or two factor authentication there. The password in /root/cloudreve-credentials.txt stops working once you change it, so delete the file after you have stored the new password safely. nginx allows two sign in attempts a second per address (with a short burst), so a script hammering the sign in page is slowed down with HTTP 429.

Step 6: Upload and share files

My Files is your drive. Use New to upload files or folders (or drag them onto the page) and to create folders. Large files are uploaded in chunks, so uploads of many gigabytes work through the browser.

Right click a file or folder (or use its menu) to Share it: Cloudreve creates a link you can protect with a password and an expiry, and lists your links under Shared by me. Anyone with the link can download without an account. Download links Cloudreve hands out carry a signature and expire, and they always use your instance's configured address.

Step 7: Connect over WebDAV

Open Connect & Mount and choose Create new account to make a WebDAV account. You can limit it to one folder and make it read only. Cloudreve shows the WebDAV address (https://<your-host>/dav), the account name and a generated password; use them in your file manager, a sync tool such as rclone, or a mobile app.

Step 8: Administer users, groups and storage

Open Dashboard in the left bar for the administration pages:

• Users: create an account for each person. Self registration is off on this image; if you want people to sign up themselves, switch registration on under Settings, and consider e-mail activation and a captcha there too.
• Groups: quotas and permissions. New users join the User group (1 GB quota, sharing on); the Admin group has 1 TB. Raise the quotas to suit your disk.
• Storage Policy: the default policy stores files on the instance under /var/lib/cloudreve/data/uploads. Add an S3 compatible policy (Amazon S3, MinIO, Cloudflare R2 and others) to keep files in object storage instead, and assign it to a group.

Some administration entries carry a Pro badge: they belong to Cloudreve Pro, a separate commercial edition from the Cloudreve project that is not part of this image; choosing them only shows information about it. The Summary page also shows the project's announcement board, which your browser loads from GitHub.

Remote Download (fetching a URL or a torrent into your drive) needs a separate downloader service that this image does not include, so it is not available out of the box.

Step 9: Use your own host name and certificate

Point a DNS record at the instance (an Elastic IP keeps the address across stop and start), then tell the instance its name. This mints a new self signed certificate for that name, updates the nginx host rule, the cross site guard, the address Cloudreve uses in its links and the address in the credentials file, and keeps the name across reboots:

sudo cloudreve-set-hostname files.example.com

To use a certificate from a public authority instead, replace /etc/ssl/cloudreve/cloudreve.crt (full chain) and /etc/ssl/cloudreve/cloudreve.key (mode 0600, owned by root) with your own and run sudo systemctl reload nginx. Running cloudreve-set-hostname again later would replace them with a new self signed pair.

Step 10: Check persistence and updates

Every service is enabled, so Cloudreve returns after a reboot or a stop and start. If the public address changes, the next boot re-issues the certificate and the address for the new name (unless you set your own name in Step 9). Unattended security upgrades keep the operating system and nginx patched:

systemctl is-enabled cloudreve cloudreve-set-host nginx unattended-upgrades

enabled
enabled
enabled
enabled

Cloudreve itself is a single program, /opt/cloudreve/cloudreve, built by cloudimg from the 4.19.1 source; /usr/share/doc/cloudimg/cloudreve/BUILD-PROVENANCE.txt records how. cloudimg publishes a new version of this image for new Cloudreve releases. To move to a newer release yourself, back up first (Step 11), replace the program with the new release from the Cloudreve releases page (the linux_amd64 archive) and run sudo systemctl restart cloudreve. Read the release notes first: a new release may migrate the database.

Step 11: Back up your files

Everything Cloudreve keeps is under /var/lib/cloudreve/data (the SQLite database cloudreve.db and the uploaded files) plus its configuration /etc/cloudreve/conf.ini. Keep the database and the files together: the database holds the encryption key for any files you store encrypted, and the file index. An EBS snapshot of the root volume (or AWS Backup on the instance) captures everything. For a file level copy, stop Cloudreve briefly:

sudo systemctl stop cloudreve
sudo tar czf cloudreve-backup.tar.gz -C / var/lib/cloudreve/data etc/cloudreve/conf.ini
sudo systemctl start cloudreve

Files kept in an S3 storage policy are backed up with your bucket.

Security notes

• No shared secret ships in the image. No password, configuration file, database, signing key or TLS key exists until your instance's first boot generates them, and the site is not published until the administrator exists and self registration is proven closed.
• Fail closed. If first boot cannot complete, nothing is published: nginx has nothing to serve and Cloudreve does not start.
• Cloudreve is confined. It listens on 127.0.0.1 only, runs as an unprivileged account that can write only /var/lib/cloudreve/data, cannot change its own program or configuration, holds no Linux capabilities, writes no core dumps and cannot read the TLS key or root's files. It is blocked from the EC2 instance metadata service, as are nginx and the first boot service.
• Cross site requests are refused for the two administrator pages that make Cloudreve contact another server (the WOPI discovery lookup and the cloud storage authorisation check). Cloudreve signs requests with a token rather than a cookie, so other web pages cannot act as you.
• Known open issues upstream. Two advisories have no fixed Cloudreve release yet: GHSA-vx2m-jpxr-xv7w (medium: after you revoke someone's access to a share, a link they had already opened can still be refreshed for a while) and GHSA-w8j7-39hp-8x59 (low: a remote downloader can place files outside the chosen folder; no downloader is installed here). cloudimg will publish an updated version when fixes are released. Every other published Cloudreve advisory is fixed in 4.19.1.
• Go libraries. The Go vulnerability scanner finds no reachable vulnerability in this build. It still lists four library advisories that have no fix or that Cloudreve never calls: two in the old AWS SDK's client side S3 encryption (GO-2022-0635, GO-2022-0646), the deprecated OpenPGP package (GO-2026-5932) and a captcha library check (GO-2023-2386).
• Restrict 22/tcp to your management network, and 80/443 to the networks that use the drive.

Architecture summary

Support

cloudimg images come with 24/7 support. Email support@cloudimg.co.uk with your AWS account ID and the instance ID. For Cloudreve itself, see the Cloudreve documentation and the Cloudreve project on GitHub.

Cloudreve is an open source project. cloudimg is not affiliated with or endorsed by the Cloudreve project.