# cargohold

cargohold lets you distribute and receive files on your own terms.
Create private links that let other people upload files to you, or send them a link
that lets them download or view the files you want them to have.

## Installation

Required dependencies

* nginx
* uwsgi
* uwsgi-plugin-python3
* sqlite3
* python3
* python3-jinja2
* python3-passlib if using `LocalBasicAuth`

Basic infrastructure

* Create a directory where cargohold will store the uploaded files
* Set the directory's owner to the user you want uwsgi to run the application under
* Edit `backend/config.py` to match your setup
* Edit `configs/nginx.config` to match your setup
	* Note that the `client_max_body_size` directive will limit the maximum size of a single uploaded file
* Install `configs/nginx.config` to `/etc/nginx/sites-enabled/`
* Edit `configs/uwsgi.ini` to match your setup
	* Note that the `limit-post` option will limit the maximum size of a single uploaded file
* Install `configs/uwsgi.ini` to `/etc/uwsgi/apps-enabled/`

Initial configuration

* Create the cargohold database by running `sqlite3 cargohold.db3 < backend/cargohold.sql`
* Update `backend/config.py` with the path to your database
* If you want to use the web administration interface, select an authentication provider in `backend/config.py`. Some providers might need additional configuration. See the section on Authentication for more details.
TBD: Extend this.

## Usage

The database stores the the following data for each alias

* *Alias*: The identifier to be appended to the base URL
* *User*: The user the identifier belongs to, for administrative and storage accounting purposes
* *Real path*: The on-disk directory name where, when prepended with both the `fileroot` and optionally, the `userdir`, the data is stored. Multiple aliases may point to the same real path.
* *Access level*: The access level this alias permits to the real path. A string consisting of any of the characters *c* (*C*reate / Upload), *r* (*R*etrieve / Read), *u* (*U*pdate), *d* (*D*elete) in any order.
* *Storage limit*: Per-alias storage limit (applied when uploading)
* *Display mode*: Parameter to the file-listing interface, customizing end-user layout.

The storage limit for each alias (applied when uploading files) is calculated as the minimum of the following parameters

* Global disk free space
* `global_limit` in `backend/config.py`
* The per-user limit minus the disk size currently used by the user, if the per-user limit is not `0`
* The per-alias limit minus the disk size currently used by the files in the alias, if the per-alias limit is not 0 / NULL

## Interface

cargohold integrates somewhat tightly with nginx using the X-Accel-Redirect mechanism.
Other httpds may provide a similar mechanism, which will need to be called out to in the
`playout()` routine in `main.py`.

## Authentication

This projects provides multiple methods to identify and authenticate users, including delegating authentication to external software.
Implementing custom authentication methods is possible and patches contributing such are welcome.

The following authentication methods are currently available:

* *NoneAuth*: The default. Does not support any logins. Use this if you want to manage cargohold exclusively via the command line or direct database interfaces
* *ExternalAuth*: Delegate authentication to an external entity. Expects the authenticated user (if any) in the REMOTE_USER environment variable
* *LocalBasicAuth*: Internal implementation of HTTP Basic Auth using htpasswd-style user databases
* *RemoteCookieAuth*: Custom authentication scheme validating a domain-wide cookie against an external service
*