Coil CMS is retired¶
The Coil project is retired due to low interest and lack of resources. Instead, we recommend using Dato CMS or Netlify CMS.
We cannot guarantee full compatibility with modern versions of Nikola, or that anything still works with Coil.
Coil CMS¶
User documentation for Coil CMS¶
Welcome to Coil CMS!
Coil CMS is a Content Management System. A Content Management System is used to administer websites. Coil is one of many of them on the market. Coil offers many benefits over the traditional CMSes to both users and administrators. Coil CMS strives to be user-friendly and easy to use.
Getting Started¶
When you access the Coil CMS app, you first need to log in by using your username and password, which were provided by the administrator. The first thing you should do is visiting the Account page and change your password to secure your account.
When you are done securing your account, you can start working.
On the Index page, there are two sections: Posts and Pages. You can create new posts or edit existing ones. Depending on the permissions you were given by the administrator, you may or may not be able to edit posts created by other users — this may cause an empty list to be displayed. If you can see posts by others, but would like to hide them, use the buttons on the top of the page to switch between display modes.
Each post displays Edit and Delete buttons, which can be used to alter contents.
After performing changes, you need to Rebuild the page in order to make them visible to the world. Sometimes, you may not be able to perform a rebuild yourself and may need the assistance of someone else. Please check with your organization for more information.
Index Page¶
On the top of the index page, you can switch between displaying only your own posts and displaying posts of all authors.
Below, Posts and Pages are displayed in separate columns. On the top of each column, you can create posts by typing their title in the field.
Warning
The post URL will be set based on the post title. It cannot be changed later!
All the posts are displayed under the creation field. You can edit or delete them.
Editing posts¶
The Edit view lets you make modifications to posts.
The topmost field is the title of the post. You can always change it. Remember that the post URL will not change, as it is set in stone during post creation.
The next line features four fields: date, author, tags and category.
Tags are comma-separated. A post can have only one category. Many date
formats are accepted. The default format used is yyyy-mm-dd hh:mm:ss UTC±hh:mm
,
(the last element being the timezone) but if you fill in your own format, it
will usually work.
The next line is the editor toolbar (which also features the Save button). Underneath
it, the post content is displayed in a box. You can edit it in any way you
like. The editor handles formatting for you, but you can click the </>
button
to edit the HTML source.
Deleting posts¶
Clicking on the red Delete button under a post will delete the post after confirming with the user.
Warning
Deleting a post is permanent.
Rebuilding the site¶
To have the changes show up on the page, you must rebuild the site.
When the site is in need of rebuilding, the menu bar displays an exclamation mark next to the Rebuild option, the word Rebuild also appears in bold.
Clicking on the Rebuild button will initiate a rebuild. The progress will be displayed.
If an error occurs, you will see the output. The error will be displayed in the Advanced information box. If you cannot understand and solve the problem yourself, contact your administrator.
Account¶
You can edit your account in the Account page. You can change your real name, e-mail and password. You can also set the preferences.
Some sites require you contact an administrator to change your details. In this case, the Account page allows you to generate a hash to let your password be changed securely (your administrator cannot recover the password from the hash).
Warning
The real name is not changed on the posts already created.
Note
If you want to change your username, you must contact an administrator.
Administrator documentation for Coil CMS¶
Setup¶
Contents
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.
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'
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.
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
.
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.
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
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.
Configuring Full Mode¶
Full Mode requires much more extra configuration.
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
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.
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
.
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
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!
Server¶
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
.
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
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;
}
}
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)
Users¶
Contents
Users of Coil are stored in the Redis database.
Information stored¶
The following data about users is stored:
Profile¶
Name | In Account | Notes |
---|---|---|
username |
Username | Used to log in |
realname |
Real name | Prominently displayed on posts |
email |
E-mail address | Used by administrators to contact users |
password |
Password | Hashed and salted using bcrypt |
Preferences¶
Name | In Account | In Permissions |
---|---|---|
want_all_posts |
Show me posts of other users by default | Want all posts |
Permissions¶
Coil uses a very granular permission system. Each user can have a different set of permissions, depending on the needs of the organization.
Name | In Account | In Permissions |
---|---|---|
active |
n/a | Active |
must_change_password |
Must change password on next login | Must change password |
is_admin |
User is an administrator | Admin |
can_edit_all_posts |
Can edit posts of other users | Can all posts |
can_upload_attachments |
Can upload attachments | Attachments |
can_rebuild_site |
Can rebuild the site | Rebuild |
can_transfer_post_authorship |
Can transfer post authorship | Transfer authorship |
Managing users and permissions¶
All administrators (people with the is_admin
permission) get access to user
management views, accessible from the user menu. They are:
Manage users¶
This is a table of all users. You can add new users at the bottom by typing in a name and clicking Create. You can also Edit, Delete or Undelete.
Bulk import¶
The last row lets you import a file with user data. TSV (Tab-Separated Values) files are accepted.
The first row MUST contain all the column names. They are:
username
realname
email
password
active
is_admin
must_change_password
can_edit_all_posts
9. want_all_posts
10 can_upload_attachments
11. can_rebuild_site
12. can_transfer_post_authorship
The following rows should contain data for the users. Passwords should be in
plain-text. All the boolean fields (active
and everything after it) accept
0
or 1
as their value.
Deleting and undeleting users¶
Even when you press the Delete button, the user stays in the database. You can then Undelete them if you change your mind.
You could delete the user straight from Redis, but this is not recommended and can have unexpected side effects.
Permissions¶
This is a table of all permissions in the system. It can be used to quickly modify the permission list for groups of users. The teal buttons can be used to select the permission for all users.
Internals¶
Database schema¶
User storage¶
Name | Type | Contents |
---|---|---|
users |
hash | Hash mapping usernames to UIDs |
user:uid |
hash | All the data we have on the user (see Users documentation) |
Caching site¶
Name | Type | Contents |
---|---|---|
site:timeline |
list | list of JSON lists of data needed to initialize a Post |
site:all_posts |
list | list of indexes for timeline matching all_posts |
site:posts |
list | list of indexes for timeline matching posts |
site:pages |
list | list of indexes for timeline matching pages |
site:rev |
string | revision (incremented at each scan; used to determine if updates are needed) |
site:lock |
string | lock on site DB |
coil.utils
¶
-
coil.utils.
ask
(query, default=None)¶ Ask a question.
-
coil.utils.
ask_yesno
(query, default=None)¶ Ask a yes/no question.
-
class
coil.utils.
SiteProxy
(db, site, logger)¶ A proxy for accessing the site in a multiprocessing-safe manner.
-
all_posts
¶ Get all_posts, reloading the site if needed.
-
pages
¶ Get pages, reloading the site if needed.
-
posts
¶ Get posts, reloading the site if needed.
-
reload_site
()¶ Reload the site from the database.
-
scan_posts
(really=True, ignore_quit=False, quiet=True)¶ Rescan the site.
-
timeline
¶ Get timeline, reloading the site if needed.
-
coil.web
¶
Appendices¶
Appendix A. Changelog¶
Version: | 1.3.12 |
---|
- 1.3.12
- Really fix #49 (forgot to press Merge pull request…)
- 1.3.11
- Fix bootstrap3 theme detection (Issue #49)
- 1.3.10
- Add coil unlock command
- Fix links to docs
- 1.3.9
- Work on non-English sites (fix #45)
- 1.3.8
- Clean up requirements (issue #40)
- 1.3.7
- Nikola v7.6.4 compatibility
- 1.3.6
- Patch URLs for HTTPS sites
- Really add descriptions for icons (got lost between branches)
- 1.3.5
- Add icon descriptions for the navigation bar
- 1.3.4
- Link to demo site in documentation
- Support reCAPTCHA for logins (for demo site)
- Support preventing some users from editing the site (for demo site)
- 1.3.3
- Remove yesterday’s new options. Please do not use v1.3.2.
- 1.3.2
- Added two options that should not be used, EVER. Please ignore them.
- 1.3.1
- Use rq from PyPI instead of GitHub
- 1.3.0
- Python 3 support
- 1.2.2
- Don’t repeat Nikola dependencies to decrease maintenance burden
- 1.2.1
- Specify deps in
setup.py
- Specify deps in
- 1.2.0
- Added support for a Limited mode, which does not require Redis and rq
- Nikola v7.4.0 compatibility
- 1.1.0
- Changed hashing mechanism to sha256 + bcrypt. Hashes will be fixed automatically on first login of each user.
- Added
passlib
dependency. - rqworker queue is now named
coil
(wasdefault
) - add trailing slashes to all URLs
- use
url_for()
- add
/rebuild/force/
(==nikola build -a
)
- 1.0.0
- RENAME TO Coil CMS
- User documentation
- Form validation
- Redis for storing data
- Rebuilding the site, using RQ as a task queue
- 0.6.0
- Permission management
setup.py
and Python packagingcomet
management command- more modern pages
- multiple issues fixed
- 0.5.0
- Switch to Flask
- Cookie-based authentication
- User management
- Style wysihtml properly
- Rename to Comet CMS
- 0.0.1
- Initial version
- Called
nikola webapp
- using bottle
- HTTP Basic “Authentication” (sorry)
- wysihtml
Appendix B. License¶
Copyright © 2014-2018 Chris Warrick, Roberto Alsina, Henry Hirsch et al.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line