realms-wiki/README.md

Realms Wiki Beta

Git based wiki written in Python Inspired by Gollum, Ghost, and Dillinger. Basic authentication and registration included.

Demo: http://realms.io This domain is being used temporarily as a demo so expect it to change.

Source: https://github.com/scragg0x/realms-wiki

Features

• Built with Bootstrap 3
• Markdown (w/ HTML Support)
• Syntax highlighting (Ace Editor)
• Live preview
• Collaboration (TogetherJS / Firepad)
• Drafts saved to local storage
• Handlebars for templates and logic

Screenshots

     

Requirements

• Python 2.7

Optional

• Nginx (if you want proxy requests, this is recommended)
• Memcached or Redis, default is memonization
• MariaDB, MySQL, Postgresql, or another database supported by SQLAlchemy, default is sqlite.
  Anon or single user does not require a database.

Installation

You will need to following packages to get started

sudo apt-get install -y python-pip python-dev libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libyaml-dev libssl-dev

Install from Pypi

Easiest way.

pip install realms-wiki

Installing from Git (Ubuntu)

git clone https://github.com/scragg0x/realms-wiki
cd realms-wiki

sudo apt-get install -y software-properties-common python-software-properties
sudo add-apt-repository -y ppa:chris-lea/node.js
sudo apt-get update
sudo apt-get install -y nodejs python-pip python-dev libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libyaml-dev libssl-dev
sudo npm install -g bower
bower install

virtualenv .venv
source .venv/bin/activate

pip install -r requirements.txt
realms-wiki start

NodeJS is for installing bower and it's used for pulling front end dependencies

OSX / Windows

This app is designed for Linux and I recommend using Vagrant to install on OSX or Windows.

Vagrant

Vagrantfile is included for development or running locally. To get started with Vagrant, download and install Vagrant and Virtualbox for your platform with the links provided

https://www.vagrantup.com/downloads.html https://www.virtualbox.org/wiki/Downloads

Then execute the following in the terminal:

git clone https://github.com/scragg0x/realms-wiki
cd realms-wiki
vagrant up

Check http://127.0.0.1:5000/ to make sure it's running.

Docker

Make sure you have docker installed. http://docs.docker.com/installation/ Here is an example run command, it will pull the image from docker hub initially.

docker run --name realms-wiki -p 5000:5000 -d realms/realms-wiki

You can build your own image if you want. Mine is based off https://github.com/phusion/baseimage-docker The Dockerfile is located in docker/Dockerfile realms/base just creates the deploy user.

Config and Setup

You should be able to run the wiki without configuration with the default config values. You may want to customize your app and the easiest way is the setup command.

realms-wiki setup

This will ask you questions and create a realms-wiki.json file in where it can find it. You can manually edit this file as well. Any config value set in realms-wiki.json will override values set in realms/config/__init__.py

Nginx Setup

sudo apt-get install -y nginx

Create a file called realms.conf in /etc/nginx/conf.d

sudo nano /etc/nginx/conf.d/realms.conf

Put the following sample configuration in that file.

server {
  listen 80;
  
  # Your domain here
  server_name wiki.example.org;
  
  # Settings to by-pass for static files 
  location ^~ /static/  {
    # Example:
    root /full/path/to/realms/;
  }
    
  location / {
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $http_host;
  
    proxy_pass http://127.0.0.1:5000/;
    proxy_redirect off;
    
  }
}

Test Nginx config

sudo nginx -t

Reload Nginx

sudo service nginx reload

Apache + mod_wsgi Setup

sudo apt-get install -y apache2 libapache2-mod-wsgi

Create a virtual host configuration in /etc/apache2/sites-available/realms_vhost:

<VirtualHost *:80>
    ServerName wiki.example.org

    WSGIDaemonProcess realms_wsgi display-name=%{GROUP}
    WSGIProcessGroup realms_wsgi
    WSGIScriptAlias / /var/www/my-realms-dir/wsgi.py

    Alias /static /full/path/to/realms/static
</VirtualHost>

Create /var/www/my-realms-dir/wsgi.py

import os
import site

# Uncomment the following lines if you are using a virtual environment

# ----------------------------------
# Enter path to your virtualenv's site-packages directory
# VENV_SITE_DIR = ".venv/lib/python2.7/site-packages"
# PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
# site.addsitedir(os.path.abspath(os.path.join(PROJECT_ROOT, VENV_SITE_DIR)))
# ----------------------------------

from realms import create_app
application = create_app()

Enable the virtual host

sudo a2ensite realms_vhost

Test your configuration

apache2ctl configtest

Reload apache

sudo service apache2 reload

Mysql Setup

sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
realms-wiki pip install python-memcached

MariaDB Setup

sudo apt-get install -y mariadb-server mariadb-client libmariadbclient-dev
realms-wiki pip install MySQL-Python

Postgres Setup

sudo apt-get install -y libpq-dev postgresql postgresql-contrib postgresql-client
realms-wiki pip install psycopg2

Don't forget to create your database.

Search

Realms wiki comes with basic search capabilities but it is not recommended for large wikis or if you require more advanced search capabilities. The backends we currently support are ElasticSearch and Whoosh.

Elasticsearch Setup

There are multiple ways to install/run elasticsearch. An easy way is to use your their repositories.

apt

wget -qO - http://packages.elasticsearch.org/GPG-KEY-elasticsearch | sudo apt-key add -
echo "deb http://packages.elasticsearch.org/elasticsearch/1.4/debian stable main" | sudo tee /etc/apt/sources.list.d/elasticsearch.list
apt-get update && apt-get install elasticsearch

For yum instructions or more details, follow the link below:

http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup-repositories.html

Configuring Elasticsearch

In your Realms Config, have the following options set:

"SEARCH_TYPE": "elasticsearch"
"ELASTICSEARCH_URL": "http://127.0.0.1:9200"

Whoosh Setup

Simply install Whoosh to your Python environment, e.g.

pip install Whoosh

Configuring Whoosh

To use Whoosh, set the following in your Realms config:

"SEARCH_TYPE": "whoosh"
"WHOOSH_INDEX": "/path/to/your/whoosh/index"
"WHOOSH_LANGUAGE": "en"

WHOOSH_INDEX has to be a path read- and writeable by Realm's user. It will be created automatically if it doesn't exist.

Whoosh is set up to use language optimization, so set WHOOSH_LANGUAGE to the language used in your wiki. For available languages, check whoosh.lang.languages. If your language is not supported, Realms will fall back to a simple text analyzer.

Running

realms-wiki start

Upstart

Setup upstart with this command.

sudo realms-wiki setup_upstart

This command requires root privs because it creates an upstart script. Also note that ports below 1024 require user root. After your config is in place use the following commands:

sudo start realms-wiki
sudo stop realms-wiki
sudo restart realms-wiki

Developement mode

This will start the server in the foreground with auto reloaded enabled

realms-wiki dev

Other commands

Usage: realms-wiki [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  auth
  configure      Set config.json, expects JSON encoded string
  create_db      Creates DB tables
  dev            Run development server
  drop_db        Drops DB tables
  pip            Execute pip commands, useful for virtualenvs
  restart        Restart server
  run            Run production server (alias for start)
  setup          Start setup wizard
  setup_upstart  Start upstart conf creation wizard
  start          Run server daemon
  status         Get server status
  stop           Stop server
  test           Run tests
  version        Output version

Access from your browser

http://localhost:5000

Templating

Realms uses handlebars partials to create templates. Each page that you create can be imported as a partial.

This page imports and uses a partial:

http://realms.io/_edit/hbs

This page contains the content of the partial:

http://realms.io/_edit/example-tmpl

I locked these pages to preserve them.
You may copy and paste into a new page to test.

Contributing

Issues and pull requests are welcome.

Python style guide

Author

Matthew Scragg scragg@gmail.com