* raincloud

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

  [[./images/screenshot.png]]

  Your friends don't use tools like [[https://github.com/magic-wormhole/magic-wormhole][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:

   #+begin_example
     /var/www/public
     ├── alice
     │   ├── big_buck_bunny.mkv
     │   ├── elephants_dream.mkv
     │   ├── rc.toml
     │   └── the_daily_dweebs.mkv
     └── inbox
         ├── logo.svg
         └── rc.toml
   #+end_example

   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.toml= file in subdirectories in which the individual permissions for the routes can be set.
   The configuration options can be [[#rctoml][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][http://localhost:5000/inbox]].

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

   Play around with the =rc.toml= 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 /raincloud/ in your environment:

   : $ pip install .

   A WSGI server like [[https://gunicorn.org/][Gunicorn]] can then be used to serve the app for example like this:

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

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

*** NixOS

    This repository is also a [[https://nixos.wiki/wiki/Flakes][Nix Flake]] which provides a [[https://nixos.org/][NixOS]] module.
    A minimal running instance can be setup for example like this:

    #+begin_src nix
      raincloud.nixosModule {
        services.raincloud = {
          enable = true;
          basePath = "/var/lib/raincloud";
          secretKey = "i_am_a_key";
        };
      }
    #+end_src

    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= |
    | =secretKey= | Flask secret key                  | =str= |               | =i_am_a_key=         |

** Configuration

   /raincloud/ provides three configuration options which can be passed to =raincloud.create_app()=:

   - =base_path= :: Base path of the raincloud
   - =secret_key= :: Flask secret key
   - =cloud_name= :: Cloud name (default: =raincloud=)

   Set them for example like this:
   : >>> app = raincloud.create_app(base_path='/home/alice/public', secret_key='super_secret', cloud_name='myCloud')

*** =rc.toml=
    :properties:
    :custom_id: rctoml
    :end:

    A =rc.toml= file can contain up to three configuration parameters:

    #+begin_src toml
      # 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
    #+end_src

** 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.