Puffin

NOTE: The project is not maintained anymore, the code is here for historical / fork purposes.

Introduction

The goal of the project is to allow average, tech-oriented user to run web applications with ease. The idea is to create an easy to host, technology agnostic private cloud. The ultimate aim is to achieve greater decentralization of web services, such as social networks, file sharing, blog or email.

While many other tools are looking at containers as a way to run massive applications, Puffin concentrates on lightweight ones, each serving just a handful of people.

You can chose to host the applications on Puffin managed platform or on your own server.

Demo

Live demo platform is available at puffin.rocks

Architecture

Puffin consists of two main components - application catalog and interface that provides means to run the applications. Any of them can be used independently - you can run the applications from the catalog directly, and you can use the interface to run your own applications that are not present in the catalog.

Technology

Puffin is based on Docker containers and for orchestration is uses Docker Compose.

Software is written in Python 3, using Flask web microframework. PosttgreSQL database is used to store the data. Nginx is used as a reverse proxy.

Deployment

Local deployment

Set-up DNS

To access installed applications from localhost you need to set-up local DNS. There are many alternative solutions to this problem, the simplest one is to add the following lines at the top of your /etc/resolv.conf file:

nameserver 127.0.0.1
options ndots:0

Which can be done by executing the following command as root:

echo -e "nameserver 127.0.0.1\noptions ndots:0\n$(cat /etc/resolv.conf)" > /etc/resolv.conf

Make sure that you disable your other local DNS server, such as dnsmasq, before running Puffin.

Clone git repository

Puffin application catalog is stored as git submodules. When cloning the repo make sure to use --recursive option:

git clone --recursive [email protected]:puffinrocks/puffin.git

Or if you have already cloned the repo then update the submodules in it:

git submodule update --init --recursive

Run Puffin

Clone the repository and use Docker Compose:

docker-compose up

Go to http://puffin.localhost to access Puffin. Log In as user "puffin", password "puffin". Emails sent from Puffin are accessible via embedded Mailhog server at http://mailhog.localhost.

If http://puffin.localhost is not accessible you can try connecting to Puffin via a port: http://localhost:8080. However, without DNS configured correctly, you won't be able to access the apps.

Puffin server is automatically reloaded on every code change thanks to reload. To rebuild the code after making more substantial change, such as modifying dependencies, run:

docker-compose build

Puffin contains several convenience commands to upgrade the database, manage users, execute internal shell, etc. To get a complete list, run:

docker-compose run puffin --help

Production deployment

Configuration

To deploy Puffin for private needs, for a single user or a limited number of users, use docker-compose-example.yml file as a basis:

cp docker-compose-example.yml docker-compose-production.yml

You need to change SERVER_NAME and VIRTUAL_HOST variables to point to your domain. You also need to set SECRET_KEY variable to a random value.

For a full list of configuration options see puffin/core/config.py.

Email

To send emails from Puffin and the applications you need to configure few environment variables before starting Puffin. It's probably easiest to register to an external email service to avoid being classified as spammer. The variables are (not all are obligatory, see puffin/core/config.py for more details):

MAIL_SERVER
MAIL_PORT
MAIL_USE_TLS
MAIL_USE_SSL
MAIL_USERNAME
MAIL_PASSWORD
MAIL_DEFAULT_SENDER
MAIL_SUPPRESS_SEND

Set-up DNS

On public server you need to configure wildacard DNS record to point to your root domain and all its subdomains.

Docker Machine

If you would like to deploy Puffin on a remote server, Docker Machine comes in handy. You can easily install Docker in the cloud or on your own server.

To instruct Docker to interact with remote server run:

eval "$(docker-machine env [machine-name])"

Run Puffin

Finally you can run Puffin:

docker-compose -f docker-compose-production.yml up -d

Configure users

Initially only "puffin" user with "puffin" password will be created - make sure to change the password before exposing puffin to the outside world. Later you can either allow other users to register themselves on your platform (via SECURITY_REGISTERABLE=True config setting) or create them manually:

docker-compose run puffin user create [login]

(The password will be the same as login, so it should be changed as soon as possible.)

Clustering

Clustering is currently not supported, but you may run apps on a separate machine than Puffin server itself. To achieve that take a look on MACHINE_* options. You also won't need network sections in your docker-compose file, since the networks will be created automatically on the remote machine.

Application Update & Backup

Application versions are regularly updated. In order to assure than new version doesn't corrupt the data, an automatic backup of all volumes is performed on every application restart.

Contributing

See CONTRIBUTING.md.

Changelog

See CHANGELOG.md.

License

AGPL, see LICENSE.txt for details.