Add setup documentation.

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jan 10, 2015 · 2883882 · 2883882
1 parent c88a0f0
commit 2883882
Show file tree

Hide file tree

Showing 10 changed files with 210 additions and 14 deletions.
diff --git a/comet/__main__.py b/comet/__main__.py
@@ -31,6 +31,7 @@
 Usage:
   comet devserver [-b | --browser] [-p <port> | --port=<port>]
   comet init [directory]
+  comet write_users
   comet -h | --help
   comet --version
 
@@ -55,6 +56,8 @@ def main():
         comet.__version__))
     if arguments[u'init']:
         sys.exit(init(arguments))
+    elif arguments[u'write_users']:
+        sys.exit(write_users(arguments))
     elif arguments[u'devserver']:
         sys.exit(devserver(arguments))
 
@@ -64,6 +67,11 @@ def init(arguments):
     return comet.init.init()
 
 
+def write_users(arguments):
+    import comet.init
+    return comet.init.write_users()
+
+
 def devserver(arguments):
     import comet.web
     port = int(arguments['--port'])

diff --git a/comet/data/templates/jinja/comet_post_edit.tmpl b/comet/data/templates/jinja/comet_post_edit.tmpl
@@ -137,8 +137,8 @@
 
 <textarea name="content" id="content-area" class="form-control" rows="24">{{ post_content }}</textarea>
 </form>
-<script src="/wysihtml/dist/wysihtml5x-toolbar.min.js"></script>
-<script src="/wysihtml/parser_rules/advanced_and_extended.js"></script>
+<script src="/bower_components/wysihtml/dist/wysihtml5x-toolbar.min.js"></script>
+<script src="/bower_components/wysihtml/parser_rules/advanced_and_extended.js"></script>
 <script type="text/javascript">
     var editor = new wysihtml5.Editor('content-area', {
     toolbar: 'toolbar',

diff --git a/comet/data/templates/jinja/comet_users_edit.tmpl b/comet/data/templates/jinja/comet_users_edit.tmpl
@@ -28,6 +28,10 @@
         <div class="panel-body">
 
             <input name="uid" type="hidden" value="{{ user.uid }}">
+            <div class="form-group">
+                <label for="name" class="col-sm-2 control-label">Username</label>
+                <div class="col-sm-10"><input class="form-control" id="username" name="username" value="{{ user.username }}" placeholder="Username" required></div>
+            </div>
             <div class="form-group">
                 <label for="name" class="col-sm-2 control-label">Real name</label>
                 <div class="col-sm-10"><input class="form-control" id="realname" name="realname" value="{{ user.realname }}" placeholder="Real name" required></div>

diff --git a/comet/data/templates/mako/comet_post_edit.tmpl b/comet/data/templates/mako/comet_post_edit.tmpl
@@ -137,8 +137,8 @@
 
 <textarea name="content" id="content-area" class="form-control" rows="24">${post_content}</textarea>
 </form>
-<script src="/wysihtml/dist/wysihtml5x-toolbar.min.js"></script>
-<script src="/wysihtml/parser_rules/advanced_and_extended.js"></script>
+<script src="/bower_components/wysihtml/dist/wysihtml5x-toolbar.min.js"></script>
+<script src="/bower_components/wysihtml/parser_rules/advanced_and_extended.js"></script>
 <script type="text/javascript">
     var editor = new wysihtml5.Editor('content-area', {
     toolbar: 'toolbar',

diff --git a/comet/data/templates/mako/comet_users_edit.tmpl b/comet/data/templates/mako/comet_users_edit.tmpl
@@ -28,6 +28,10 @@
         <div class="panel-body">
 
             <input name="uid" type="hidden" value="${user.uid}">
+            <div class="form-group">
+                <label for="name" class="col-sm-2 control-label">Username</label>
+                <div class="col-sm-10"><input class="form-control" id="username" name="username" value="${user.username}" placeholder="Username" required></div>
+            </div>
             <div class="form-group">
                 <label for="name" class="col-sm-2 control-label">Real name</label>
                 <div class="col-sm-10"><input class="form-control" id="realname" name="realname" value="${user.realname}" placeholder="Real name" required></div>

diff --git a/comet/init.py b/comet/init.py
@@ -26,8 +26,21 @@
 # SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
 from __future__ import print_function, unicode_literals
+import pkg_resources
+import os
 
 
 def init():
     print("ERROR: Not implemented.")
     return 255
+
+
+def write_users():
+    with open('comet_users.json', 'wb') as fh:
+        fh.write(pkg_resources.resource_string(
+            'comet', os.path.join('data', 'comet_users.json')))
+
+    print("Wrote comet_users.json.\n")
+    print("Username: admin")
+    print("Password: admin")
+    return 0
diff --git a/comet/web.py b/comet/web.py
@@ -589,17 +589,17 @@ def rescan():
     return redirect('/')
 
 
-@app.route('/wysihtml/<path:path>')
-def serve_wysihtml(path):
-    """Serve wysihtml files.
+@app.route('/bower_components/<path:path>')
+def serve_bower_components(path):
+    """Serve bower components.
 
     This is meant to be used ONLY by the internal dev server.
     Please configure your web server to handle requests to this URL::
 
-        /wysihtml/ => comet/data/bower_components/wysihtml
+        /bower_components/ => comet/data/bower_components
     """
     res = pkg_resources.resource_filename(
-        'comet', os.path.join('data', 'bower_components', 'wysihtml'))
+        'comet', os.path.join('data', 'bower_components'))
     return send_from_directory(res, path)
 
 
@@ -753,6 +753,7 @@ def acp_users_edit():
             alert = 'Must set a password.'
             alert_status = 'danger'
             action = 'save_fail'
+        user.username = data['username']
         user.realname = data['realname']
         for p in PERMISSIONS:
             setattr(user, p, p in data)

diff --git a/docs/README.rst b/docs/README.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,16 +3,32 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Comet CMS's documentation!
-=====================================
+Comet CMS
+=========
 
-Contents:
+User documentation
+------------------
+
+Currently none.
+
+watch this space
+
+Administrator documentation
+---------------------------
 
 .. toctree::
    :maxdepth: 2
 
+   setup
    web
-   README
+
+
+Appendices
+----------
+
+.. toctree::
+   :maxdepth: 2
+
    AUTHORS
    CHANGELOG
    LICENSE

diff --git a/docs/setup.rst b/docs/setup.rst
@@ -0,0 +1,151 @@
+=====
+Setup
+=====
+
+.. index:: setup
+
+.. contents::
+
+How Comet works alongside Nikola
+================================
+
+Comet requires Nikola to work.  `Nikola`_ is a static site generator, written
+in Python.  Comet manages the files that are then used by Nikola to build the
+site.
+
+As such, you must configure Nikola first before you start Comet.
+
+Virtualenv
+==========
+
+Create a virtualenv in ``/var/comet`` and instal Comet in it.
+
+.. code-block:: console
+
+    # virtualenv-2.7 /var/comet
+    # cd /var/comet
+    # source bin/activate
+    # pip install comet uwsgi
+
+Nikola and ``conf.py``
+======================
+
+Start by setting up Nikola.  This can be done using ``nikola init``.
+
+.. code-block:: console
+
+    # mkdir /var/comet
+    # cd /var/comet
+    # nikola init my_comet_site
+    Creating Nikola Site
+    ====================
+
+    [a wizard will guide you through configuration]
+
+    [2015-01-10T18:16:35Z] INFO: init: Created empty site at my_comet_site.
+    # cd my_comet_site
+
+Then, you must make some changes to the config:
+
+ * Add ``COMET_SECRET_KEY`` — a bunch of random characters, needed for sessions.
+   **Store it in a safe place** — git is not one!  You can use
+   ``os.urandom(24)`` to generate something good.
+ * Add ``COMET_URL`` — the URL under which Comet can be accessed.
+ * Modify ``POSTS`` and ``PAGES``, replacing ``.txt`` by ``.html``.
+
+
+Finally, you must add `some CSS`__ for wysihtml5.  The easiest way to do this
+is by downloading the raw ``.css`` file as ``files/assets/css/custom.css``.
+
+__ https://github.com/Voog/wysihtml/blob/master/examples/css/stylesheet.css
+
+First build
+===========
+
+When you are done configuring nikola, run ``nikola build`` and chown the
+``my_comet_site`` site directory recursively to nobody, or whatever
+user Comet will run as.  Comet must be able to write to this directory.
+
+.. code-block:: console
+
+    # nikola build
+    # chown -Rf nobody:nobody .
+
+Users
+=====
+
+Run ``comet write_users``:
+
+.. code-block:: console
+
+    # comet write_users
+    Wrote comet_users.json.
+
+    Username: admin
+    Password: admin
+
+
+You will be able to add more users and change the admin credentials (which you
+should do!) later.  See also: :doc:`users`
+
+Server: uWSGI and nginx
+=======================
+
+For testing purposes, you can use ``comet devserver``.  It should **NOT** be used
+in production.  You should use uWSGI Emperor and nginx in a real environment.
+
+Sample uWSGI configuration:
+
+.. code-block:: ini
+
+    [uwsgi]
+    emperor = true
+    socket = 127.0.0.1:3031
+    chdir = /var/comet/my_comet_site
+    master = true
+    threads = 5
+    binary-path = /var/comet/bin/uwsgi
+    virtualenv = /var/comet
+    module = comet.web
+    callable = app
+    plugins = python2
+    uid = nobody
+    gid = nobody
+    processes = 3
+    logger = file:/var/comet/my_comet_site/uwsgi.log
+
+
+(``python2`` may also be ``python``, this depends on your environment)
+
+Sample nginx configuration:
+
+.. code-block:: nginx
+
+    server {
+        listen 80;
+        server_name comet.example.com;
+        root /var/comet/my_comet_site;
+
+        location / {
+            include uwsgi_params;
+            uwsgi_pass 127.0.0.1:3031;
+        }
+
+        location /favicon.ico {
+            alias /var/comet/my_comet_site/output/favicon.ico;
+        }
+
+        location /assets {
+            alias /var/comet/my_comet_site/output/assets;
+        }
+
+        location /comet_assets {
+            alias /var/comet/lib/python2.7/site-packages/comet/data/comet_assets;
+        }
+
+        location /bower_components {
+            alias /var/comet/lib/python2.7/site-packages/comet/data/bower_components;
+        }
+    }
+
+.. _Nikola: https://getnikola.com/