raincloud/README.org

• raincloud
  • Example
  • Installation
  • Deployment
    • NixOS
    • Docker
  • Configuration
    • rc.conf
  • Troubleshooting

raincloud

A self-hosted file sharing cloud for you and your friends.

Your friends don't use tools like magic-wormhole and you don't want to upload private data to third party file hosters? You want to save a file from a computer that doesn't belong to you and are always losing your USB sticks? raincloud solves those problems by providing a simple self-hosted file sharing platform.

Features

• No users, just password protectable dynamic HTTP routes
• No database backend, just a flat directory structure
• Permissions per route individually configurable via plain-text files

Example

Assuming you host raincloud at https://cloud.example.com and it is configured to run on /var/www/public with the following directory structure:

  /var/www/public
  ├── alice
  │   ├── big_buck_bunny.mkv
  │   ├── elephants_dream.mkv
  │   ├── rc.conf
  │   └── the_daily_dweebs.mkv
  └── inbox
      ├── logo.svg
      └── rc.conf

Then the following two routes exist:

• https://cloud.example.com/alice
• https://cloud.example.com/inbox

This is determined by the presence of a rc.conf file in subdirectories in which the individual permissions for the routes can be set. The configuration options can be seen below. All other routes, including http://cloud.example.com, return 404 Not Found.

This repository contains the above listed public directory for testing raincloud locally. Just execute the following two commands and navigate to http://localhost:5000/inbox.

$ pip install -r requirements.txt
$ ./run.py

Play around with the rc.conf files and create new directories to see how raincloud behaves. No restarting is needed.

The password for the alice directory is movie_night!.

Installation

Execute the following command in the repository to install the raincloud module in your environment:

$ pip install .

Deployment

A WSGI server like Gunicorn can then be used to serve the app for example like this:

$ gunicorn "raincloud:create_app(base_path='public')"

Note that currently only one worker makes sense due to server side session caching.

NixOS

This repository is also a Nix Flake which provides a NixOS module. A minimal running instance can be setup for example like this:

  raincloud.nixosModule {
    services.raincloud = {
      enable = true;
      basePath = "/var/lib/raincloud";
    };
  }

All configuration options are:

Option	Description	Type	Default value	Example
address	Bind address of the server	str	127.0.0.1	0.0.0.0
port	Port on which the server listens	int	8000	5000
user	User under which the server runs	str	raincloud	alice
group	Group under which the server runs	str	raincloud	users
cloudName	Name of the raincloud	str	raincloud	bobsCloud
basePath	Base path of the raincloud	str		/var/lib/raincloud

Docker

A Dockerfile, based on Alpine Linux, is available in the repository. You can build a local raincloud image with the following command:

$ docker build -t raincloud:latest github.com/Deleh/raincloud

A container of the image exposes raincloud at port 8000 and uses the base directory /var/www/raincloud. Use dockers -p flag to map the port on your host and -v flag to mount a local base directory:

$ docker run -p <local_port>:8000 -v <path_to_local_base_directory>:/var/www/raincloud raincloud:latest

If you want to change the cloud name you can pass the cloud_name environment variable to the container:

$ docker run -p <local_port>:8000 -v <path_to_local_base_directory>:/var/www/raincloud -e "cloud_name=podcloud" raincloud:latest

Configuration

raincloud provides two configuration options which can be passed to raincloud.create_app():

base_path

Base path of the raincloud

cloud_name

Cloud name (default: raincloud)

Set them for example like this:

>>> app = raincloud.create_app(base_path='/home/alice/public', cloud_name='myCloud')

rc.conf

A rc.conf file looks like the following snippet and can contain up to three configuration parameters after the [raincloud] section:

  [raincloud]

  # Insert a password hash to enable password protection for this directory
  # Use one of the following commands to create a hash:
  #   mkpasswd -m sha-256
  #   mkpasswd -m sha-512
  #
  #hashed_password =

  # Set this to 'true' to allow file downloads from this directory
  download = false

  # Set this to 'true' to allow file uploads to this directory
  upload = false

Troubleshooting

The filesize which can be uploaded may be limited by your web server. When using Nginx for example, the following configuration parameter can be used to increase the upload files size:

client_max_body_size 100M;

Are you getting internal server errors? Check the directory permissions. The user which runs raincloud must have at least read permissions to allow downloads and execute permissions to allow uploads.