Installing a Poser App on Linux
This guide tries to walk through the basic process for installing a Poser app, aka. any app based on Rattail.
But there is no such "Poser" app - that is just a placeholder name. So for purposes of example below, we will be using 'rattail-demo' instead of Poser. That way you can perform the instructions as shown, and things will "just work" (i.e. you will have installed the rattail-demo app).
- Linux (only tested with Debian and Ubuntu)
- Python (comes with Linux, nothing special required)
development packages for certain libraries (e.g. python-dev)
- virtualenvwrapper (not technically required but these docs assume its use)
Note that which "development packages" you need will depend on the particular app and its dependencies.
TODO: Need to document (or link to existing doc for) the setup of virtualenvwrapper.
Each app installed should get its own virtual environment, unless there's a good reason not to do that. (I don't recall having found such a reason yet.)
In fact you may need to install the same app (i.e. package) to multiple environments. Depends on your needs of course, but please use a virtual environment in all cases.
You can name it anything you like but it's often most convenient to give your virtualenv the same name as the app package you'll install to it. Again we're assuming virtualenvwrapper here (but create the virtualenv however you like really):
This should auto-activate your new virtualenv, but if you need to re-activate it later, that's just (with virtualenvwrapper):
You can also de-activate the virtualenv with:
Installing the App
Typically this is just a matter of running pip install with whatever app you like. Note that your virtualenv should be activated for this step! In our example:
workon rattail-demo pip install rattail-demo
If you get errors here, it may be due to your not having installed some "development packages" as mentioned above in Prerequisites section.
Note that the above assumes a "production" install of the app, where the latest version of package is downloaded from PyPI (or similar index). For development and staging servers (and in some cases even production) you may instead want to install "from source". Usually this is done to stay on the bleeding edge of development instead of waiting for new code to be "released" officially.
In the case of rattail-demo, the package available from PyPI is often rather stale, so installing from source makes perfect sense for that one. In which case you can run the following command instead of the one shown above:
pip install -e git+https://rattailproject.org/git/rattail-demo.git#egg=rattail_demo
(TODO: as of this writing that fails b/c of missing rattail-corepos dependency)
Configuring the App
Please see Configuration to get a broader understanding, but for now we'll try to keep it basic.
There is no hard rule regarding the name of config files, but in practice there is definitely a convention. Almost all Poser apps will have a few config files in common. Some apps may have additional config files for various purposes.
Config files which "all" Poser apps may have in common:
rattail.conf - "true primary" config file for the app; often will contain "secrets" (in which case should not be world-readable); logs to rattail.log
quiet.conf - simple wrapper config which suppresses some console logging output; intended for ad-hoc use
cron.conf - simple wrapper config which suppresses even more console logging output, and redirects logging to cron.log
Config files which are common in general, but presence will vary depending on the app:
web.conf - "primary web app" config, needed for traditional web UI; logs to web.log
webapi.conf - "web API app" config, needed for REST API (experimental as of this writing!); logs to webapi.log
datasync.conf - config specific to 'datasync' daemon; logs to datasync.log
filemon.conf - config specific to 'filemon' daemon; logs to filemon.log
tempmon.conf - config specific to 'tempmon' (server or client) daemon; logs to tempmon.log
bouncer.conf - config specific to 'bouncer' daemon; logs to bouncer.log