From 6267305a9c3148c69680bc5f8e137ab923d64aab Mon Sep 17 00:00:00 2001 From: Lance Edgar Date: Mon, 6 Oct 2025 17:06:53 -0500 Subject: [PATCH] Add RattailBONE-Installation --- RattailBONE-Installation.-.md | 121 ++++++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 RattailBONE-Installation.-.md diff --git a/RattailBONE-Installation.-.md b/RattailBONE-Installation.-.md new file mode 100644 index 0000000..7172b31 --- /dev/null +++ b/RattailBONE-Installation.-.md @@ -0,0 +1,121 @@ +# BONE Installation + +This document aims to get you up and running with Rattail BONE as soon as possible. + +The process is known to work on the platforms listed below. Please [[email Lance|mailto:lance@edbob.org]] if you have success with others. + +## Requirements + +There are several things you'll need before Rattail and BONE even come into play. + +### Operating System + +Until further testing is done, it is assumed you'll be running on one of the following platforms: + +**Microsoft Windows** + + * Windows XP Professional + +**Linux** + + * Ubuntu 10.04 + +### Database + +Since Rattail inherits lots of back-ends from SQLAlchemy, the database requirement is pretty vague indeed. Nonetheless you will need some type of database back-end for Rattail. This can be as simple as SQLite, where you don't really need to do anything, to PostgreSQL, where you need to get a database server up and running as a completely additional step. For the sake of this document we'll use SQLite because of its simplicity, and it is hoped that the reader will further investigate the other options on his/her own. Supported back-ends include: + + * MySQL + * PostgreSQL + * SQLite + * etc. + +See [[http://www.sqlalchemy.org/docs/core/engines.html#supported-dbapis|SQLAlchemy's full list of supported databases]]. + +### Python + +Please note that Python 2.6 is all that is currently supported. Python 2.7 "probably" works but has not been tested. Python 3.0 most likely does not work, and Python 2.5 is known to have at least one issue on Windows. + +To install Python, Linux users probably don't need to do anything, but just in case (on Ubuntu): + +```sh +sudo apt-get install python +``` + +Windows users will probably need to visit http://python.org/download/ to fetch an installer. + +### Setuptools + +The `setuptools` library is needed to assist installation. Ubuntu users can: + +```sh +sudo apt-get install python-setuptools +``` + +Windows users should [[http://pypi.python.org/pypi/setuptools|go here]] (toward the bottom of the page) and fetch the `setuptools-*-win32-py*.exe` installer appropriate to the version of Python they're running. + +## Installation + +Fetch and install BONE (and Rattail, and other dependencies) like this (Ubuntu users should prefix this with `sudo`): + +```sh +easy_install rattail-bone +``` + +Windows users: If you just get a "command not found" message then you should probably add the Python "scripts" folder (e.g. `C:\Python26\Scripts`) to your `PATH` variable. + +## Configuration + +Configuration is handled by two separate files, one for Rattail and one for BONE. + +### Rattail + +First of all Rattail needs a configuration file. This command will create the file in its standard location and launch an editor on it: + +```sh +rattail config +``` + +This file needs to contain at the very least a database connection URL, for example: + +```ini +[DEFAULT] +sqlalchemy.url = sqlite:////path/to/my/sqlite/file +``` + +Replace the sample URL above with your own. The SQLite database file can exist wherever makes the most sense to your situation; BONE itself will not assume (or really even know) anything about its location. + +### BONE + +BONE also needs a configuration file. This command will create the file (and remind you to launch an editor on it): + +```sh +paster make-config rattail-bone bone.ini +``` + +Note that you can replace "bone.ini" with any filename. It doesn't matter where this file exists except that ''you'' know where that is; again, put it wherever makes the most sense to your situation. + +You don't actually need to edit this file, but you're welcome to if you like. + +## Setup + +Now that all the software is installed and the configuration is defined, use this command to install the database: + +```sh +paster setup-app bone.ini +``` + +Note again that "bone.ini" can be whichever file you created a moment ago. + +## Serving the App + +At this point you should be able to run the Paster server: + +```sh +paster serve bone.ini +``` + +Again "bone.ini" should be whichever file you created a moment ago. + +The server should print a message with the exact URL you can connect to it with, but most likely it's just: http://127.0.0.1:5000 + +That's it! Have fun.