2.1. Setup¶
Contents
2.1.1. How Coil works alongside Nikola¶
Coil requires Nikola to work. Nikola is a static site generator, written in Python. Coil manages the files that are then used by Nikola to build the site.
As such, you must configure Nikola first before you start Coil. You can also use an existing site.
2.1.2. Virtualenv¶
Create a virtualenv in /srv/coil
and install Coil, Nikola, uWSGI and rq in it.
# virtualenv-2.7 /srv/coil
# cd /srv/coil
# source bin/activate
# pip install nikola coil uwsgi
# pip install 'git+https://github.com/nvie/rq.git#egg=rq'
2.1.3. Nikola and conf.py
¶
Start by setting up Nikola. This can be done using nikola init
.
# mkdir /srv/coil
# cd /srv/coil
# nikola init my_coil_site
Creating Nikola Site
====================
[a wizard will guide you through configuration]
[2015-01-10T18:16:35Z] INFO: init: Created empty site at my_coil_site.
# cd my_coil_site
Then, you must make some changes to the config:
COIL_SECRET_KEY
— a bunch of random characters, needed for sessions. Store it in a safe place — git is not one! You can useos.urandom(24)
to generate something good.COIL_URL
— the URL under which Coil can be accessed._MAKO_DISABLE_CACHING = True
- Modify
POSTS
andPAGES
, replacing.txt
with.html
.- You must set the mode (Limited vs Full) and configure it accordingly — see next section for details.
2.1.3.1. CSS for the site¶
You must add some CSS for wysihtml5. The easiest way to do this
is by downloading the raw .css
file and saving it as files/assets/css/custom.css
.
2.1.3.2. Special config for demo sites¶
The former demo site used the following two settings, which might also be useful for some environments:
COIL_LOGIN_CAPTCHA
— if you want reCAPTCHA to appear on the login page- (aimed at plugic environments, eg. the demo site), set this to a dict of
{'enabled': True, 'site_key': '', 'secret_key': ''}
and fill in your data. If you don’t want a CAPTCHA, don’t set this setting.
COIL_USERS_PREVENT_EDITING
— list of user IDs (integers) that cannot edit their profiles.
2.1.4. Limited Mode vs. Full Mode¶
Coil can run in two modes: Limited and Full.
Limited Mode:
- does not require a database, is easier to setup
- stores its user data in
conf.py
(no ability to modify users on-the-fly) - MUST run as a single process (
processes=1
in uWSGI config)
Full Mode:
- requires Redis and RQ installed and running
- stores its user data in the Redis database (you can modify users on-the-fly)
- may run as multiple processes
2.1.4.1. Configuring Limited Mode¶
You need to add the following to your config file:
COIL_LIMITED = True
COIL_USERS = {
'1': {
'username': 'admin',
'realname': 'Website Administrator',
'password': '$bcrypt-sha256$2a,12$St3N7xoStL7Doxpvz78Jve$3vKfveUNhMNhvaFEfJllWEarb5oNgNu',
'must_change_password': False,
'email': 'info@getnikola.com',
'active': True,
'is_admin': True,
'can_edit_all_posts': True,
'wants_all_posts': True,
'can_upload_attachments': True,
'can_rebuild_site': True,
'can_transfer_post_authorship': True,
},
}
The default user is admin
with the password admin
. New users can be
created by creating a similar dict. Password hashes can be calculated on the
Account page. Note that you are responsible for changing user passwords
(users should provide you with hashes and you must add them manually and
restart Coil) — consider not setting must_change_password
in Limited mode.
Continue with First build.
2.1.4.2. Configuring Full Mode¶
Full Mode requires much more extra configuration.
2.1.4.2.1. Redis¶
You need to set up a Redis server. Make sure it starts at boot.
2.1.4.2.2. RQ¶
You need to set up a RQ worker. Make sure it starts
at boot, after Redis. Here is a sample .service
file for systemd:
[Unit]
Description=RQWorker Service
After=redis.service
[Service]
Type=simple
ExecStart=/srv/coil/bin/rqworker coil
User=nobody
Group=nobody
[Install]
WantedBy=multi-user.target
2.1.4.2.3. Users¶
Run coil write_users
:
# coil write_users
Redis URL [redis://]:
Username: admin
Password: admin
You will be able to add more users and change the admin credentials (which you should do!) later. See also: Users.
2.1.4.2.4. conf.py additions¶
You must add COIL_LIMITED = False
and COIL_REDIS_URL
, which is an URL to
your Redis database. The accepted formats are:
redis://[:password]@localhost:6379/0
(TCP)rediss://[:password]@localhost:6379/0
(TCP over SSL)unix://[:password]@/path/to/socket.sock?db=0
(Unix socket)
The default URL is redis://localhost:6379/0
.
2.1.5. First build¶
When you are done configuring Nikola, Coil and any other dependencies, run
nikola build
. This will build an empty Nikola site that can now be hosted
outside. You need to do this, because Coil itself uses some assets from this
site.
# nikola build
2.1.6. Permissions¶
# chown -Rf nobody:nobody .
Chown my_coil_site
recursively to nobody
, or whatever
user Coil will run as. Coil must be able to write to this directory.
Make sure to fix permissions if you fool around the site directory!
2.1.7. Server¶
2.1.7.1. Built-in development server¶
For testing purposes, or for ad-hoc usage (especially in Limited mode), you can
just run coil devserver
. However, it should NOT be used in production.
In a public environment, especially in Full mode, you should use uWSGI Emperor
and nginx instead.
If you are on Windows and the server crashes, try python -m coil devserver
.
2.1.7.2. uWSGI¶
Sample uWSGI configuration:
Note
python2
may also be python
, depending on your environment.
Warning
processes
MUST be set to 1 if running in Limited Mode.
[uwsgi]
emperor = true
socket = 127.0.0.1:3031
chdir = /srv/coil/my_coil_site
master = true
threads = 5
binary-path = /srv/coil/bin/uwsgi
virtualenv = /srv/coil
module = coil.web
callable = app
plugins = python2,logfile
uid = nobody
gid = nobody
processes = 3
logger = file:/srv/coil/my_coil_site/uwsgi.log
2.1.7.3. nginx¶
Sample nginx configuration:
Note
This configuration block assumes you followed the guide. You may need to change the location aliases to match your system.
You should change server_name
to something you own and can run the
server on.
server {
listen 80;
server_name coil.example.com;
root /srv/coil/my_coil_site;
location / {
include uwsgi_params;
uwsgi_pass 127.0.0.1:3031;
}
location /favicon.ico {
alias /srv/coil/my_coil_site/output/favicon.ico;
}
location /assets {
alias /srv/coil/my_coil_site/output/assets;
}
location /coil_assets {
alias /srv/coil/lib/python2.7/site-packages/coil/data/coil_assets;
}
location /bower_components {
alias /srv/coil/lib/python2.7/site-packages/coil/data/bower_components;
}
}
2.1.7.4. Other web servers¶
You can also use any other web or WSGI server. You must take care of:
- location aliases for
/favicon.ico
,/assets
,/coil_assets
,/bower_components
— see above for sample destinations - correct process count (must be 1 in Limited mode)