Installation

We’ll try to keep this brief but link to further reading where needed.

Prerequisites

• Linux strongly recommended

• Python 3

• database in PostgreSQL or MySQL (or ??)

Linux is recommended because effectively “all” production testing has happened on Debian and Ubuntu specifically. But the project is all Python so should run anywhere as long as the code is accounting for that…which to be honest it may not be in all places yet.

The assumption is that you already have Python 3, unless on Windows in which case see Python.

You can ostensibly use any backend supported by SQLAlchemy to store your Messkit database; however in practice PostgreSQL has had a gazillion times more production testing and is highly recommended. MySQL/MariaDB also have seen some basic testing and are believed to work fine.

Note that the database need not live on the same machine as the Messkit app.

The Messkit installer currently only supportes PostgreSQL and MySQL/MariaDB, so if another backend is desired it just means the installer can’t automate setup for you, but manual setup is still possible.

Messkit

Create a virtual environment for Messkit, e.g.:

python3 -m venv /path/to/envs/messkit

If you’re new to these see also Virtual Environment.

Be sure to activate your virtual environment:

source /path/to/envs/messkit/bin/activate

Next install the Messkit package to your environment:

pip install Messkit

Now setup your database backend. Messkit will need a database, and it will need to connect to that database with a particular set of user credentials.

Depending on your backend type, create the user account. The default username is rattail so we’ll assume that here. Whatever username and password you set will be needed for the final Messkit setup.

PostgreSQL:

sudo -u postgres createuser -P rattail

MySQL:

sudo mysql -e "create user rattail@localhost"
sudo mysql -e "alter user rattail@localhost identified by 'THEPASSWORD'"

Next create the database itself.

PostgreSQL:

sudo -u postgres createdb -O rattail messkit

MySQL:

sudo mysqladmin create messkit
sudo mysql -e "grant all on messkit.* to rattail@localhost"

Finally run the Messkit installer. When it asks for db type you can enter mysql or just accept the postgresql default. You are advised to answer “yes” to all yes/no questions:

messkit -n install

With that complete you should be able to run the web app with:

cd /path/to/envs/messkit
bin/pserve file+ini:app/web.conf

Please note, you should have created an admin user during the Messkit installer. You should be able to login to the web app with those credentials, but by default even an “admin” user can’t do much of anything.

However an admin user has a special power - they can “become root” which means the same as it does for Linux. When you do this all features which exist become unlocked. The expectation for a “production” app is that you would define roles and grant them permissions etc. as needed. But while testing you can just “become root” and not really worry about the permissions.

Upgrading

Upgrades are done directly in the web app, and basic details of each are recorded.

Default menu location is Admin -> Messkit Upgrades. Create a new upgrade, make sure it is enabled, then execute it. That’s all!

Although, the default upgrade script will not actually restart the web app for you, so after an upgrade completes successfully you should restart the web app manually.

Starting Over

A major goal for Messkit is to make “starting over” a simple thing, to encourage users to experiment with it. Maybe you even keep one app in production while having others reserved for trying new things.

The installer is of course a big part of that, so hopefully it’s easy enough, but suggestions for improvements are always welcome!

But depending on your situation you may prefer to “destroy” the previous attempt before installing a new app etc. Really that is just 2 steps:

Remove entirely your “app” folder, e.g.:

cd /path/to/envs/messkit
rm -rf app

Then drop and re-create your database. Commands for creating a database are shown above, but here are the drops.

PostgreSQL:

sudo -u postgres dropdb messkit

MySQL:

sudo mysqladmin drop messkit

With that done you can re-run the installer:

messkit -n install