Using cockatiel

Requirements

• cockatiel requires Python 3.4 or newer
• cockatiel has only been tested in Linux so far

Installation

Installing cockatiel is really straightforward. We recommend that you set it up inside a virtual environment in order to isolate its dependencies from other python projects that you might use. Inside the Python 3 virtual environment you can then just run:

$ pip install cockatiel

to obtain the latest release.

Warning

Before using cockatiel for your project, please make sure that you read and understood the Assumptions that cockatiel makes about your requirements.

Command-line options

Cockatiel is currently configured via command-line parameters. Logging is performed via stdout.

Simple replicating file storage.

usage: python3 -m cockatiel [-h] [--port PORT] [--host HOST] --storage PATH
                            --queue PATH [--url URL] [--node URL] [-v]

Options:

--port=8080, -p=8080
	The port that this cockatiel server should bind to.
--host=0.0.0.0, -H=0.0.0.0
	The IP address of the interface that this cockatiel server should listen on.
--storage	The path to the directory to store the actual files in. The cockatiel process needs permission to read and write files and create new subdirectories at this location.
--queue	Path to a directory to store the retry queue. The cockatiel process needs permission to read, write and delete file at this location.
--url=	The URL this service is publicly reachable at, e.g. http://10.1.1.1:8123/foo or https://mydomain.com/media, depending on your reverse proxy setup.
--node	Specify this option once for every other node on your cluster. Every value should be a valid URL prefix like http://10.1.1.2:8012
-v=False, --verbose=False
	Enable debugging output. Without this flag, only errors and warnings are logged.

Running cockatiel as a service

To automatically run cockatiel at system startup, you can register it as a system service.

TBD systemd example

Adding new nodes to the cluster

If you’re system is growing and you’d like to add a new node to the cluster, you’ll need to go through the following steps in the given order:

1. Set up and start cockatiel on the new server, including all existing servers in its cluster configuration.
2. Add the URL of the new server to the cluster configuration on all other nodes, then restart those nodes.
3. Manually copy over the complete storage directory from one of the existing nodes to your new node, e.g. using rsync.

Using cockatiel for a Django application

We have a Django storage backend for cockatiel available at django-cockatiel.