lightweight webapp catalog based on containers, with user interface à la mobile app store
Python HTML CSS Mako
Switch branches/tags
Clone or download
loomchild Upgrade to bcrypt 3.x and Python 3.6.5
bcrypt 2.x version wasn't compatible with latest Python - I had
gnu-crypt.h missing error.

Related to #20.
Latest commit 461163e May 10, 2018


Build Status


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.


Live demo platform is available at

Puffin Front Page


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.


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.


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:

options ndots:0

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

echo -e "nameserver\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

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


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/


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/ for more details):


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






AGPL, see LICENSE.txt for details.