realms-wiki/README.md

325 lines
9 KiB
Markdown
Raw Normal View History

2014-09-04 06:25:48 +03:00
# Realms Wiki Beta
Git based wiki written in Python
2014-09-10 22:37:48 +03:00
Inspired by [Gollum][gollum], [Ghost][ghost], and [Dillinger][dillinger].
2014-09-04 06:25:48 +03:00
Basic authentication and registration included.
2014-09-04 16:06:22 +03:00
Demo: http://realms.io
This domain is being used temporarily as a demo so expect it to change.
2014-10-17 22:30:00 +03:00
Source: https://github.com/scragg0x/realms-wiki
2014-09-04 06:25:48 +03:00
## Features
- Built with Bootstrap 3
2014-10-17 22:30:00 +03:00
- Markdown (w/ HTML Support)
2014-09-04 06:25:48 +03:00
- Syntax highlighting (Ace Editor)
- Live preview
2014-10-17 22:30:00 +03:00
- Collaboration (TogetherJS / Firepad)
- Drafts saved to local storage
- Handlebars for templates and logic
2014-09-04 06:25:48 +03:00
## Screenshots
2014-09-10 19:35:11 +03:00
[<img src="https://db.tt/Q2XHGRnT" width=340 />](https://db.tt/Q2XHGRnT)&nbsp;[<img width=340 src="https://db.tt/pIZ4w2oN" />](https://db.tt/pIZ4w2oN)&nbsp;[<img width=340 src="https://db.tt/ERLmDHrk" />](https://db.tt/ERLmDHrk)&nbsp;[<img width=340 src="https://db.tt/Ls08ocLh" />](https://db.tt/Ls08ocLh)&nbsp;[<img width=340 src="https://db.tt/7QVfXFQ4" />](https://db.tt/7QVfXFQ4)&nbsp;[<img width=340 src="https://db.tt/Lna3BOm1" />](https://db.tt/Lna3BOm1)
2014-09-04 06:25:48 +03:00
## Requirements
2014-10-17 22:30:00 +03:00
2014-09-04 06:25:48 +03:00
- Python 2.7
2014-10-17 22:30:00 +03:00
### Optional
2014-09-04 06:25:48 +03:00
- 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.
2014-09-02 17:29:04 +03:00
## Installation
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
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)
2014-10-17 22:30:00 +03:00
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
2014-10-17 22:30:00 +03:00
NodeJS is for installing [bower](http://bower.io) and it's used for pulling front end dependencies
2014-09-04 06:25:48 +03:00
### OSX / Windows
2014-10-17 22:30:00 +03:00
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.
2014-09-21 01:30:34 +03:00
### 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](docker/Dockerfile) realms/base just creates the deploy user.
## Config and Setup
2014-10-17 22:30:00 +03:00
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
2014-10-17 22:30:00 +03:00
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
2014-09-04 06:25:48 +03:00
sudo apt-get install -y nginx
2014-09-02 17:29:04 +03:00
2014-09-09 23:36:23 +03:00
Create a file called realms.conf in /etc/nginx/conf.d
sudo nano /etc/nginx/conf.d/realms.conf
2014-09-09 23:36:23 +03:00
Put the following sample configuration in that file.
2014-09-09 23:46:41 +03:00
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/static/;
}
2014-09-09 23:46:41 +03:00
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;
}
}
2014-09-09 23:36:23 +03:00
Test Nginx config
sudo nginx -t
2014-09-09 23:36:23 +03:00
Reload Nginx
sudo service nginx reload
2014-09-02 17:29:04 +03:00
### 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
2014-11-19 17:43:34 +02:00
### 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._
2014-11-19 17:43:34 +02:00
## 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 only
backend we currently support is ElasticSearch
### 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"
2014-09-04 06:25:48 +03:00
## Running
2014-10-17 22:30:00 +03:00
realms-wiki start
### Upstart
Setup upstart with this command.
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
sudo realms-wiki setup_upstart
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
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:
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
sudo start realms-wiki
sudo stop realms-wiki
sudo restart realms-wiki
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
### Developement mode
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
This will start the server in the foreground with auto reloaded enabled
2014-09-04 06:25:48 +03:00
2014-10-17 22:30:00 +03:00
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
2014-09-04 06:25:48 +03:00
Access from your browser
2014-09-04 16:59:19 +03:00
http://localhost:5000
2014-09-04 06:25:48 +03:00
2014-10-02 01:14:54 +03:00
## Templating
2014-09-04 16:06:22 +03:00
2014-10-02 01:14:54 +03:00
Realms uses handlebars partials to create templates.
Each page that you create can be imported as a partial.
2014-10-02 01:14:54 +03:00
This page imports and uses a partial:
2014-10-02 01:14:54 +03:00
2014-10-17 22:30:00 +03:00
http://realms.io/_edit/hbs
2014-10-02 01:14:54 +03:00
This page contains the content of the partial:
2014-10-02 01:14:54 +03:00
2014-10-17 22:30:00 +03:00
http://realms.io/_edit/example-tmpl
I locked these pages to preserve them.
You may copy and paste into a new page to test.
2014-10-02 01:14:54 +03:00
2014-10-17 22:30:00 +03:00
## Contributing
Issues and pull requests are welcome.
[Python style guide](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html)
2014-09-04 16:06:22 +03:00
## Author
Matthew Scragg <scragg@gmail.com>
2014-09-10 22:37:48 +03:00
[gollum]: https://github.com/gollum/gollum
[ghost]: https://github.com/tryghost/Ghost
[dillinger]: https://github.com/joemccann/dillinger/