Personal/realms-wiki
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

Merge pull request #57 from magic890/patch-2

Browse source 
Improved installation steps + other small improvements.
This commit is contained in:
Matthew Scragg 2015-07-01 14:31:47 -07:00
parent e84f2fa2e2 87efa345c4
commit b9f1bca23b
1 changed files with 67 additions and 58 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

121
README.md
View file

@ -11,13 +11,13 @@ Source: https://github.com/scragg0x/realms-wiki
## Features ## Features
- Built with Bootstrap 3 - Built with Bootstrap 3.
- Markdown (w/ HTML Support) - Markdown (w/ HTML Support).
- Syntax highlighting (Ace Editor) - Syntax highlighting (Ace Editor).
- Live preview - Live preview.
- Collaboration (TogetherJS / Firepad) - Collaboration (TogetherJS / Firepad).
- Drafts saved to local storage - Drafts saved to local storage.
- Handlebars for templates and logic - Handlebars for templates and logic.
## Screenshots ## Screenshots
@ -29,24 +29,38 @@ Source: https://github.com/scragg0x/realms-wiki
### Optional ### Optional
- Nginx (if you want proxy requests, this is recommended) - Nginx (if you want proxy requests, this is recommended).
- Memcached or Redis, default is memonization - Memcached or Redis, default is memonization.
- MariaDB, MySQL, Postgresql, or another database supported by SQLAlchemy, default is sqlite. - MariaDB, MySQL, Postgresql, or another database supported by SQLAlchemy, default is sqlite.
Anon or single user does not require a database. Anon or single user does not require a database.
## Installation ## Installation
You will need the following packages to get started ### Requirements installation
You will need the following packages to get started:
#### Ubuntu
sudo apt-get install -y python-pip python-dev libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libyaml-dev libssl-dev sudo apt-get install -y python-pip python-dev libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libyaml-dev libssl-dev
### Install from Pypi #### CentOS / RHEL
Easiest way. yum install -y python-pip python-devel.x86_64 libxslt-devel.x86_64 libxml2-devel.x86_64 libffi-devel.x86_64 libyaml-devel.x86_64 libxslt-devel.x86_64 zlib-devel.x86_64 openssl-devel.x86_64 python-pbr gcc
#### OSX / Windows
This app is designed for Linux and I recommend using Vagrant to install on OSX or Windows.
### Realms Wiki installation via PyPI
The easiest way. Install it using Python Package Index:
pip install realms-wiki pip install realms-wiki
### Installing from Git (Ubuntu) ### Realms Wiki installation via Git
#### Ubuntu
git clone https://github.com/scragg0x/realms-wiki git clone https://github.com/scragg0x/realms-wiki
cd realms-wiki cd realms-wiki
@ -64,19 +78,15 @@ Easiest way.
pip install -r requirements.txt pip install -r requirements.txt
realms-wiki start realms-wiki start
NodeJS is required for installing [bower](http://bower.io) and it's used for pulling front end dependencies NodeJS is required for installing [bower](http://bower.io) and it's used for pulling front end dependencies.
### OSX / Windows ### Realms Wiki via Vagrant
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. 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 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.vagrantup.com/downloads.html
https://www.virtualbox.org/wiki/Downloads - https://www.virtualbox.org/wiki/Downloads
Then execute the following in the terminal: Then execute the following in the terminal:
@ -84,9 +94,9 @@ Then execute the following in the terminal:
cd realms-wiki cd realms-wiki
vagrant up vagrant up
Check ```http://127.0.0.1:5000/``` to make sure it's running. Check [http://127.0.0.1:5000/](http://127.0.0.1:5000/) to make sure it's running.
### Docker ### Realms Wiki via Docker
Make sure you have docker installed. http://docs.docker.com/installation/ 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. Here is an example run command, it will pull the image from docker hub initially.
@ -94,28 +104,28 @@ 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 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 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. The Dockerfile is located in [docker/Dockerfile](docker/Dockerfile) `realms/base` just creates the deploy user.
## Config and Setup ## Config and Setup
You should be able to run the wiki without configuration with the default config values. You should be able to run the wiki without configuration using the default config values.
You may want to customize your app and the easiest way is the setup command. You may want to customize your app and the easiest way is the setup command:
realms-wiki setup realms-wiki setup
This will ask you questions and create a realms-wiki.json file in where it can find it. This will ask you questions and create a `realms-wiki.json` file in where you can find it.
You can manually edit this file as well. 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``` Any config value set in `realms-wiki.json` will override values set in `realms/config/__init__.py`.
### Nginx Setup ### Nginx Setup
sudo apt-get install -y nginx sudo apt-get install -y nginx
Create a file called realms.conf in /etc/nginx/conf.d Create a file called `realms.conf` in `/etc/nginx/conf.d`
sudo nano /etc/nginx/conf.d/realms.conf sudo nano /etc/nginx/conf.d/realms.conf
Put the following sample configuration in that file. Put the following sample configuration in that file:
server { server {
listen 80; listen 80;
@ -136,16 +146,15 @@ Put the following sample configuration in that file.
proxy_pass http://127.0.0.1:5000/; proxy_pass http://127.0.0.1:5000/;
proxy_redirect off; proxy_redirect off;
} }
} }
Test Nginx config Test Nginx config:
sudo nginx -t sudo nginx -t
Reload Nginx Reload Nginx:
sudo service nginx reload sudo service nginx reload
@ -153,7 +162,7 @@ Reload Nginx
sudo apt-get install -y apache2 libapache2-mod-wsgi sudo apt-get install -y apache2 libapache2-mod-wsgi
Create a virtual host configuration in /etc/apache2/sites-available/realms_vhost: Create a virtual host configuration in `/etc/apache2/sites-available/realms_vhost`
<VirtualHost *:80> <VirtualHost *:80>
ServerName wiki.example.org ServerName wiki.example.org
@ -165,7 +174,7 @@ Create a virtual host configuration in /etc/apache2/sites-available/realms_vhost
Alias /static /full/path/to/realms/static Alias /static /full/path/to/realms/static
</VirtualHost> </VirtualHost>
Create /var/www/my-realms-dir/wsgi.py Create `/var/www/my-realms-dir/wsgi.py`
import os import os
import site import site
@ -182,19 +191,19 @@ Create /var/www/my-realms-dir/wsgi.py
from realms import create_app from realms import create_app
application = create_app() application = create_app()
Enable the virtual host Enable the virtual host:
sudo a2ensite realms_vhost sudo a2ensite realms_vhost
Test your configuration Test your configuration:
apache2ctl configtest apache2ctl configtest
Reload apache Reload apache:
sudo service apache2 reload sudo service apache2 reload
### Mysql Setup ### MySQL Setup
sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev sudo apt-get install -y mysql-server mysql-client libmysqlclient-dev
realms-wiki pip install python-memcached realms-wiki pip install python-memcached
@ -213,13 +222,13 @@ _Don't forget to create your database._
## Search ## Search
Realms wiki comes with basic search capabilities but it is not recommended Realms wiki comes with basic search capabilities, however this is not recommended
for large wikis or if you require more advanced search capabilities. The for large wikis or if you require more advanced search capabilities.
backends we currently support are ElasticSearch and Whoosh. We currently support Elasticsearch and Whoosh as alternative backend.
### Elasticsearch Setup ### Elasticsearch Setup
There are multiple ways to install/run elasticsearch. An easy way is to use your their There are multiple ways to install/run Elasticsearch. An easy way is to use your their
repositories. repositories.
**apt** **apt**
@ -228,7 +237,7 @@ repositories.
echo "deb http://packages.elasticsearch.org/elasticsearch/1.4/debian stable main" | sudo tee /etc/apt/sources.list.d/elasticsearch.list 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 apt-get update && apt-get install elasticsearch
For yum instructions or more details, follow the link below: For `yum` instructions or more details, follow the link below:
http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup-repositories.html http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup-repositories.html
@ -253,9 +262,9 @@ To use Whoosh, set the following in your Realms config:
"WHOOSH_INDEX": "/path/to/your/whoosh/index" "WHOOSH_INDEX": "/path/to/your/whoosh/index"
"WHOOSH_LANGUAGE": "en" "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_INDEX has to be a path readable 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. 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. If your language is not supported, Realms will fall back to a simple text analyzer.
## Running ## Running
@ -264,12 +273,12 @@ If your language is not supported, Realms will fall back to a simple text analyz
### Upstart ### Upstart
Setup upstart with this command. Setup upstart with this command:
sudo realms-wiki setup_upstart sudo realms-wiki setup_upstart
This command requires root privs because it creates an upstart script. This command requires root priveleges because it creates an upstart script.
Also note that ports below 1024 require user root. Also note that ports below `1024` require user root.
After your config is in place use the following commands: After your config is in place use the following commands:
sudo start realms-wiki sudo start realms-wiki
@ -279,7 +288,7 @@ After your config is in place use the following commands:
### Developement mode ### Developement mode
This will start the server in the foreground with auto reloaded enabled This will start the server in the foreground with auto reloaded enabled:
realms-wiki dev realms-wiki dev
@ -307,13 +316,13 @@ This will start the server in the foreground with auto reloaded enabled
test Run tests test Run tests
version Output version version Output version
Access from your browser Access from your browser:
http://localhost:5000 http://localhost:5000
## Templating ## Templating
Realms uses handlebars partials to create templates. Realms uses Handlebars partials to create templates.
Each page that you create can be imported as a partial. Each page that you create can be imported as a partial.
This page imports and uses a partial: This page imports and uses a partial:
@ -325,12 +334,12 @@ This page contains the content of the partial:
http://realms.io/_edit/example-tmpl http://realms.io/_edit/example-tmpl
I locked these pages to preserve them. I locked these pages to preserve them.
You may copy and paste into a new page to test. You can copy and paste into a new page for testing purposes.
## Contributing ## Contributing
Issues and pull requests are welcome. Issues and pull requests are welcome.
Please follow the code style guide.
[Python style guide](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html) [Python style guide](http://google-styleguide.googlecode.com/svn/trunk/pyguide.html)