Demo¶
Running a demo site¶
Atramhasis comes with a demo site include. This allows you to quickly evaluate and inspect the software. To get started, just download Atramhasis from pypi and install it. We recommend doing this in a virtualenvironment.
$ mkvirtualenv atramhasis_demo
$ pip install -U atramhasis
Once Atramhasis is installed, you can call upon a pyramid scaffold to generate the demo site.
$ pcreate -s atramhasis_demo atramhasis_demo
$ cd atramhasis_demo
This creates a local demo package you can run with just a few more commands:
# setup
$ pip install -r requirements-dev.txt
$ python setup.py develop
# download and install client side libraries
$ cd atramhasis_demo/static
$ bower install
$ cd admin
$ bower install
$ cd ../../..
# create or upgrade database
$ alembic upgrade head
# intialize sample data
$ initialize_atramhasis_db development.ini
# compile translations
$ python setup.py compile_catalog
# generate full RDF dumps (not necessary for basic functionality)
$ dump_rdf development.ini
# start server
$ pserve development.ini
The Atramhasis demo instance is now running on your localhost at port 6543. To reach it, open your browser and surf to the address http://localhost:6543.
You will be greeted by the Atramhasis front page. From this page you can start searching and browsing the thesauri. You can also start editing the thesauri by surfing to http://localhost:6543/admin. The demo instance does not requires you to login to access the admin module. If you want to run Atramhasis in a production environment, you can easily write your own security module. This enables you to use the security mechanisms (eg. LDAP, Active Directory, a custom users database, …) that your organisation requires. Please consult the documentation on Security customisation for further information on this topic.
Running a demo site with Docker¶
There is a Docker image available that allows you to quickly get a demo instance up and running. The Docker image contains the demo application and the LDF server.
After installing Docker for your operating system, you can simply pull the image and run a container. Once you’ve executed the following commands, you should be able to visit the demo application in your browser on http://localhost:6543. A LDF-server is also included in the demo, which is accessible on http://localhost:3000.
$ sudo docker pull atramhasis/demo
$ sudo docker run -p 6543:6543 -p 3000:3000 atramhasis/demo
Alternatively, you can run a specific version of Atramhasis (starting from atramhasis 0.6.4):
$ sudo docker pull atramhasis/demo:0.6.4
$ sudo docker run -p 6543:6543 -p 3000:3000 atramhasis/demo:0.6.4
While this is a fast and easy way to get a first impression of Atramhasis, please be aware that any edits you make when running the image, will be discarded when you stop the Docker container. If you want to test the application over a longer period of time, this is probably not what you’re looking for. If you need persistence, but still want to use Docker, you can customise the Dockerfile to suit your needs.
Running a demo site on Heroku¶
This section will tell you how to deploy an Atramhasis demo (or your own implementation) in the cloud. We’ll use Heroku, since this provider allows for a free Python instance (dyno) with a limited Postgresql database.
Create an account on Heroku and make sure you have Heroku Toolbelt installed. Prepare your local Heroku setup
Note
More information on running Python apps on Heroku can be found on the Heroku dev center.
Atramhasis scaffold¶
Create an Atramhasis scaffold (if you want to deploy an existing scaffold, skip this step)
$ mkvirtualenv atramhasis_heroku
$ pip install -U atramhasis
$ pcreate -s atramhasis_demo atramhasis_heroku
$ cd atramhasis_heroku
Git repository¶
Make sure your atramhasis_heroku folder is a git repository.
$ git init
$ git add .
$ git commit -m "initial commit"
requirements.txt¶
Update the requirements.txt file, make sure it contains a reference to atramhasis and to waitress.
Note
waitress has to be in the requirements.txt file for our Heroku deployment, requirements-dev.txt will be ignored.
run file¶
Create run
with the following content.
#!/bin/bash
set -e
python setup.py develop
python runapp.py
Note
Make sure to chmod +x run
before continuing. The develop
step is
necessary because the current package must be installed before Paste can
load it from the INI file.
runapp.py¶
Create a runapp.py
file.
import os
from paste.deploy import loadapp
from waitress import serve
if __name__ == "__main__":
port = int(os.environ.get("PORT", 5000))
app = loadapp('config:production.ini', relative_to='.')
serve(app, host='0.0.0.0', port=port)
Note
After creating the necessary files, commit them in your local git repository
Initialize the Heroku stack¶
$ heroku create
Postgresql¶
Attach an Heroku Postgres add-on to your application
$ heroku addons:add heroku-postgresql:hobby-dev
It can take a couple of minutes before your db is ready. You can wait for it to be ready using this command.
$ heroku pg:wait
When ready, check the connection url and copy paste it into your production.ini file
$ heroku config | grep HEROKU_POSTGRESQL
Also change the alembic.ini file to check your production.ini file instead of development.ini
ini_location = %(here)s/production.ini
Make sure to commit everything and push it to Heroku
$ git commit -a
$ git push heroku master
Note
More info on provisioning a database
Preparing the app¶
Open a remote console on your app
$ heroku run bash
This will start a console inside your remote Python virtualenv, so you can use all your libraries.
Run the commands to prepare your application
$ python setup.py develop
$ alembic upgrade head
$ initialize_atramhasis_db production.ini
$ python setup.py compile_catalog
$ dump_rdf production.ini
Note
Close the remote console!
Run the app¶
Run your app by starting one worker
$ heroku scale web=1
Check to see if your app is running.
$ heroku ps
Take a look at the logs to debug any errors if necessary.
$ heroku logs -t
Your app should now be available on the application url.