# HG changeset patch # User Ludovic Chabant # Date 1519629578 28800 # Node ID 1dcebff866f16d609e110c41d59c24a5bb56e30b # Parent e8511fed42a39335608fd07401df18fab5f528aa docs: Add more information about the administration panel. diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel-assets/commit.png Binary file docs/docs/30_admin-panel-assets/commit.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel-assets/edit.png Binary file docs/docs/30_admin-panel-assets/edit.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel-assets/listsrc.png Binary file docs/docs/30_admin-panel-assets/listsrc.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel-assets/publish.png Binary file docs/docs/30_admin-panel-assets/publish.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel-assets/writenew.png Binary file docs/docs/30_admin-panel-assets/writenew.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel.md --- a/docs/docs/30_admin-panel.md Sun Feb 25 23:18:47 2018 -0800 +++ b/docs/docs/30_admin-panel.md Sun Feb 25 23:19:38 2018 -0800 @@ -12,66 +12,19 @@ To run the administration panel, type: ``` -$ chef admin run - * Running on http://localhost:8090/ (Press CTRL+C to quit) - +chef serve --admin ``` -Now copy paste the specified URL (`http://localhost:8090/`) into your favorite -browser's address bar and you should see "FoodTruck", PieCrust's administrative +Now browse to the admin URL (`http://localhost:8080/pc-admin`) with your +favorite browser and you should see "FoodTruck", PieCrust's administrative panel. -The navigation menu on the left should have: - -* The dashboard. -* One entry for each of your page sources. -* An interface to publish your website. - -## The Dashboard - -This is where you can see a summary of your website, with links to see your list -of already existing content. - -If your website content is also stored in a version control system, you can see -what's currently edited in the "_Work in Progress_" section. - -> Right now, FoodTruck only supports Mercurial for source control. - - -## Page Sources - -For each source, you can list the existing pages: - -![Page Sources]({{assets.listsrc}}) - -Clicking on any link will let you edit that page. +* [Using the administration panel][using]: explains how the administration panel + works, and how you can improve its handling of you website with a few settings + in your site's configuration. -You can also create a new page by clicking the appropriate entry in the left -navigation menu. You'll have to fill up information similar to what you specify -to the `chef prepare` command: - -![New Page]({{assets.writenew}}) - -Once you created a page, or click a link for an existing one, you can edit the -page: - -![Edit Page]({{assets.edit}}) - -Note that if your website is stored in a VCS, you'll have the ability to commit -the page file if you want, but using the dropdown on the "_Save_" button: +* [Deploying the administration panel][deploy]: gives a few tips for making the + administration panel available on your production server. -![Commit Page]({{assets.commit}}) - - -## Publishing - -You also have a UI for running your publish targets. The descriptions shown for -each target are taken from a `description` entry in their configuration -settings. - -![Publish]({{assets.publish}}) - -Clicking any "_Execute_" button will publish your website using the -corresponding target. You'll see some notifications popup on the bottom right to -indicate the progress of the operation. - +[using]: {{docurl('admin-panel/using-the-panel')}} +[deploy]: {{docurl('admin-panel/deploying-the-panel')}} diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/01_using-the-panel-assets/commit.png Binary file docs/docs/30_admin-panel/01_using-the-panel-assets/commit.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/01_using-the-panel-assets/edit.png Binary file docs/docs/30_admin-panel/01_using-the-panel-assets/edit.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/01_using-the-panel-assets/listsrc.png Binary file docs/docs/30_admin-panel/01_using-the-panel-assets/listsrc.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/01_using-the-panel-assets/publish.png Binary file docs/docs/30_admin-panel/01_using-the-panel-assets/publish.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/01_using-the-panel-assets/writenew.png Binary file docs/docs/30_admin-panel/01_using-the-panel-assets/writenew.png has changed diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/01_using-the-panel.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/30_admin-panel/01_using-the-panel.md Sun Feb 25 23:19:38 2018 -0800 @@ -0,0 +1,61 @@ +--- +title: Using the Administration Panel +--- + +The navigation menu on the left should have: + +* The dashboard. +* One entry for each of your page sources. +* An interface to publish your website. + +## The Dashboard + +This is where you can see a summary of your website, with links to see your list +of already existing content. + +If your website content is also stored in a version control system, you can see +what's currently edited in the "_Work in Progress_" section. + +> Right now, FoodTruck only supports Mercurial for source control. + + +## Page Sources + +For each source, you can list the existing pages: + +![Page Sources]({{assets.listsrc}}) + +Clicking on any link will let you edit that page. + +You can also create a new page by clicking the appropriate entry in the left +navigation menu. You'll have to fill up information similar to what you specify +to the `chef prepare` command: + +![New Page]({{assets.writenew}}) + +Once you created a page, or click a link for an existing one, you can edit the +page: + +![Edit Page]({{assets.edit}}) + +Note that if your website is stored in a VCS, you'll have the ability to commit +the page file if you want, but using the dropdown on the "_Save_" button: + +![Commit Page]({{assets.commit}}) + + +## Publishing + +You also have a UI for running your [publish targets][pub]. The descriptions shown for +each target are taken from a `description` entry in their configuration +settings. + +![Publish]({{assets.publish}}) + +Clicking any "_Execute_" button will publish your website using the +corresponding target. You'll see some notifications popup on the bottom right to +indicate the progress of the operation. + + +[pub]: {{docurl("publishing")}} + diff -r e8511fed42a3 -r 1dcebff866f1 docs/docs/30_admin-panel/02_deploying-the-panel.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/30_admin-panel/02_deploying-the-panel.md Sun Feb 25 23:19:38 2018 -0800 @@ -0,0 +1,115 @@ +--- +title: Deploying the Administration Panel +--- + +Deploying the administration panel to your online server will let you, well, +administrate your website. This has a few benefits, like letting you create and +edit blog posts while on the move, from a browser or from client apps that +support it. Downsides of course include a more complicated server setup, and +security risks. + +The administration panel is a [Flask][] application, so the [Flask deployment +documentation][flask_deploy] applies here as well. + +[flask]: http://flask.pocoo.org/ +[flask_deploy]: http://flask.pocoo.org/docs/0.12/deploying/ + + +## WSGI Application + +The first thing to do is to make the WSGI application that will be served by +your web server. Create a `.wsgi` file with the following contents: + +``` +from piecrust.wsgiutil import get_admin_app +application = get_admin_app('/path/to/website') +``` + +It might be a good idea to log any application errors, at least at first, to +a log file that you can inspect if there's a problem: + +``` +import logging +from piecrust.wsgiutil import get_admin_app + +application = get_admin_app( + '/path/to/website', + log_level=logging.INFO, + log_file='/path/to/logfile.log') +``` + + +## `mod_wsgi` (Apache) + +You can follow the steps from the [Flask documentation for +Apache][flask_apache]. + +Here are a few things to watch our for however. + +* In the `WSGIDaemonProcess` directive, you can specify a Python home directory to + use, which is useful if you are using a virtual environment to not have to + install PieCrust in your system's Python environment. + +* You need to set `WSGIPassAuthorization` to `On` for client apps to be able to + correctly authenticate with your website. + +* Alias the administration panel's static files to the `/static` sub-folder so + that all the CSS and pictures show up correctly. Don't forget to also set the + proper access for Apache. + +For example: + + WSGIDaemonProcess piecrust_admin user=www-data threads=4 \ + python-home=/path/to/virtualenv + WSGIScriptAlias /pc-admin /path/to/wsgi/file.wsgi + WSGIPassAuthorization On + Alias /pc-admin/static /path/to/virtualenv/lib/site-packages/piecrust/admin/static + + + Require all granted + + + + Require all granted + + +The rest is pretty much the same as what the Flask documentation says. + + +[flask_apache]: http://flask.pocoo.org/docs/0.12/deploying/mod_wsgi/ + + +## Using Client Applications + +The PieCrust administration panel supports the [Micropub][] protocol, so +applications like [Micro.blog][mb] can be used to create new blog posts. + +This however requires you to specify ways to authenticate yourself as the owner +of your website. Thankfully, this is done quite easily with the [IndieAuth][] +protocol: + +* Add some markup to your website's `` section so that you point to, say, + your Twitter profile with a `rel="me"` attribute. +* Add some authorization endpoints that handle all the security handshaking + stuff. + +For instance: + + + + + +Make sure your Twitter profile has a link that points back at your website. +That's it! + +Now you need to indicate to client applications what to do to make new blog +posts. You also do this by adding an entry in your `` section: + + + +That's it too! + + +[mb]: https://micro.blog/ +[micropub]: https://en.wikipedia.org/wiki/Micropub_(protocol) +[indieauth]: https://indieauth.com/