Add initial docs

docs/install.rst

@@ -0,0 +1,157 @@
+
+.. highlight:: sh
+
+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 :doc:`rattail-manual:base/install/windows/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.
+
+.. _`supported by SQLAlchemy`: https://docs.sqlalchemy.org/en/13/dialects/index.html
+
+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 :doc:`rattail-manual:base/venv`.
+
+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