Personal
/
realms-wiki
1
0
Fork 0
Code Issues Pull-Requests Releases Wiki Aktivität

Update README and Dockerfile

Dieser Commit ist enthalten in:
Theodotos Andreou 2016-09-23 22:04:17 +03:00
Ursprung 853a1b42aa
Commit 70e619ff11
2 geänderte Dateien mit 86 neuen und 413 gelöschten Zeilen
Statistiken anzeigen Patch-Datei herunterladen Vergleichs-Datei herunterladen Alle Dateien ausklappen Alle Dateien einklappen

495
README.md
Datei anzeigen

@ -1,451 +1,120 @@
# Realms Wiki Beta
# Realms Wiki Beta with LDAP support
Git based wiki written in Python
Inspired by [Gollum][gollum], [Ghost][ghost], and [Dillinger][dillinger].
Basic authentication and registration included.
This is a recipe of [Realms Wiki](https://github.com/scragg0x/realms-wiki) patched so that a docker image is build with LDAP support. The Dockefile actually downloads the Realms Wiki code from [Matthew Scragg's](https://github.com/scragg0x) original repo and not from my fork.
Demo: http://realms.io
This domain is being used temporarily as a demo so expect it to change.
### Differences from the master repo
Source: https://github.com/scragg0x/realms-wiki
* The docker image is based on Debian jessie instead of Ubuntu trusty
* The *flask_ldap_login* is patched using [Stephane Martin's](https://github.com/stephane-martin) [patch](https://github.com/ContinuumIO/flask-ldap-login/issues/26) to eliminate the "Internal Server Error" message when logging in with LDAP.
## Features
### Clone the repo
- 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.
```
git clone git@github.com:theodotos/realms-wiki.git
```
## Screenshots
### Build the image
[<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)
```
cd realms-wiki/docker
docker build -t realm-wiki-img .
```
## Requirements
### Pull it from Docker Hub
- Python 2.7
If you prefer using my build you can pull it from Docker Hub:
### Optional
```
docker pull theodotos/realms-wiki
```
- 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.
### Run the container
## Installation
Create a *realms-wiki* volume:
### Requirements installation
```
docker volume create --name realms-wiki
```
You will need the following packages to get started:
For your own build:
#### Ubuntu
```
docker run -d --name realms-wiki -p 5000:5000 --volume realms-wiki:/home/wiki realms-wiki-img
```
sudo apt-get install -y python-pip python-dev libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libyaml-dev libssl-dev libsasl2-dev libldap2-dev
For my build:
#### CentOS / RHEL
```
docker run -d --name realms-wiki -p 5000:5000 --volume realms-wiki:/home/wiki theodotos/realms-wiki:latest
```
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 openldap2-devel cyrus-sasl-devel python-pbr gcc
#### OSX / Windows
### Configure the container
This app is designed for Linux and I recommend using Vagrant to install on OSX or Windows.
Prepare a *realms-wiki.json* file like this:
### Realms Wiki installation via PyPI
The easiest way. Install it using Python Package Index:
pip install realms-wiki
### Realms Wiki installation via 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 libsasl2-dev libldap2-dev
sudo npm install -g bower
bower install
virtualenv .venv
source .venv/bin/activate
pip install -r requirements.txt
realms-wiki start
NodeJS is required for installing [bower](http://bower.io) and it's used for pulling front end dependencies.
### Realms Wiki via 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/](http://127.0.0.1:5000/) to make sure it's running.
### Realms Wiki via 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
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:
realms-wiki setup
This will ask you questions and create a `realms-wiki.json` file.
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, however this is not recommended
for large wikis or if you require more advanced search capabilities.
We currently support Elasticsearch and Whoosh as alternative backend.
### 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"
Optionally, also set the following option to configure which fields are searchable:
"ELASTICSEARCH_FIELDS": ["name"]
Allowable values are `"name"`, `"content"`, `"username"`, `"message"`. The default is `["name"]`.
### 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 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`.
If your language is not supported, Realms will fall back to a simple text analyzer.
## Authentication
### Local
Local default will be done using a backend database as defined in the config.
To disable local authentication, put the following your config.
"AUTH_LOCAL_ENABLE": false
### LDAP (beta)
Realms uses the following library to authenticate using LDAP. https://github.com/ContinuumIO/flask-ldap-login
It supports direct bind and bind by search.
Use these examples as a guide and place it in your realms-wiki.json config.
#### Bind By Search Example
In this example, BIND_DN and BIND_AUTH are used to search and authenticate. Leaving them blank implies anonymous authentication.
```
cat > realms-wiki.json << EOF
{
"ALLOW_ANON": true,
"BASE_URL": "http://realms.example.com",
"CACHE_TYPE": "simple",
"DB_URI": "sqlite:////home/wiki/data/wiki.db",
"PORT": 5000,
"REGISTRATION_ENABLED": true,
"SEARCH_TYPE": "simple",
"SECRET_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"SITE_TITLE": "Example Wiki",
"WIKI_PATH": "/home/wiki/data/repo",
"LDAP": {
"URI": "ldap://localhost:8389",
"BIND_DN": "",
"BIND_AUTH": "",
"USER_SEARCH": {"base": "dc=realms,dc=io", "filter": "uid=%(username)s"},
"URI": "ldap://ldap.example.com:389",
"BIND_DN": "cn=realms,ou=services,dc=example,dc=com",
"BIND_AUTH": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"USER_SEARCH": {
"base": "ou=people,dc=example,dc=com",
"filter": "uid=%(username)s"},
"START_TLS": true,
"KEY_MAP": {
"username":"cn",
"email": "mail"
}
}
#### Direct Bind Example
"LDAP": {
"URI": "ldap://localhost:8389",
"BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
"KEY_MAP": {
"username":"cn",
"email": "mail",
},
"username": "uid",
"email": "mail"},
"OPTIONS": {
"OPT_PROTOCOL_VERSION": 3,
}
"OPT_PROTOCOL_VERSION": 3}
}
}
EOF
```
**NOTE: you can use the `apg -n1 -x65 -m65` command to generate a SECRET_KEY**
### OAuth (beta)
Copy the config over to the container:
Realms currently supports Github, Twitter, Facebook and Google. Each provider requires a key and secret.
Put them in your `realms-wiki.json` config file. Use the example below.
```
cp realms-wiki.json realms-wiki:/home/wiki/realms-wiki
```
"OAUTH": {
"twitter": {
"key": "",
"secret": ""
},
"github": {
"key": "",
"secret": ""
}
}
Restart the container:
### Authentication by reverse proxy
```
docker restart realms-wiki
```
If you configured realms behind a reverse-proxy or a single-sign-on, it is possible to delegate authentication to
the proxy.
Browse to http://realms.example.com:5000 to test it.
"AUTH_PROXY": true
Note: of course with that setup you must ensure that **Realms is only accessible through the proxy**.
### Some tips about STARTTLS
Example Nginx configuration:
location / {
auth_basic "Restricted";
auth_basic_user_file /etc/nginx/.htpasswd;
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_set_header REMOTE_USER $remote_user;
proxy_pass http://127.0.0.1:5000/;
proxy_redirect off;
}
By default, Realms will look for the user ID in `REMOTE_USER` HTTP header. You can specify another header name with:
If you ldap backend is not protected by a publicly trusted CA, you will need to add your Internal ROOT CA certificate in the trusted CA list of your container.
"AUTH_PROXY_HEADER_NAME": "LOGGED_IN_USER"
Copy your Internal ROOT CA certificate in the container:
```
docker cp example-rootca.crt realms-wiki:/usr/local/share/ca-certificates/
```
## Running
Add your Internal CA as trusted in the trusted CA list:
realms-wiki start
### Upstart
Setup upstart with this command:
```
docker exec -i -t -u root realms-wiki /usr/sbin/update-ca-certificates
```
sudo realms-wiki setup_upstart
This command requires root priveleges 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
### Development 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 can copy and paste into a new page for testing purposes.
## Contributing
Issues and pull requests are welcome.
Please follow the code style guide.
[Python style guide](https://www.python.org/dev/peps/pep-0008/)
## Author
Matthew Scragg <scragg@gmail.com>
[gollum]: https://github.com/gollum/gollum
[ghost]: https://github.com/tryghost/Ghost
[dillinger]: https://github.com/joemccann/dillinger/
Restart the container and try again.
docker exec -i -t -u root realms-wiki /usr/sbin/update-ca-certificates

4
docker/Dockerfile
Datei anzeigen

@ -52,6 +52,10 @@ ENV REALMS_DB_URI='sqlite:////home/wiki/data/wiki.db'
RUN mkdir /home/wiki/data && touch /home/wiki/data/.a
VOLUME /home/wiki/data
ADD flask_ldap_login.patch /home/wiki/
RUN patch ./.venv/lib/python2.7/site-packages/flask_ldap_login/__init__.py < \
/home/wiki/flask_ldap_login.patch
EXPOSE 5000
CMD . .venv/bin/activate && \