doc/tutorials/base/blog-in-five-minutes.rst
author Philippe Pepiot <ph@itsalwaysdns.eu>
Tue, 31 Mar 2020 18:22:05 +0200
changeset 12966 6cd938c29ca3
parent 12922 3d3e34813d25
permissions -rw-r--r--
[server] Make connection pooler configurable and set better default values Drop the configuration connections-pool-size and add new configurations options: * connections-pool-min-size. Set to 0 by default so we open connections only when needed. This avoid opening min-size*processes connections at startup, which is, it think, a good default. * connections-pool-max-size. Set to 0 (unlimited) by default, so we move the bottleneck to postgresql. * connections-idle-timeout. Set to 10 minutes. I don't have arguments about this except that this is the default in pgbouncer.

.. -*- coding: utf-8 -*-

.. _TutosBaseBlogFiveMinutes:

Get a blog running in five minutes!
-----------------------------------

For Debian or Ubuntu users, first install the following packages
(:ref:`DebianInstallation`)::

    python3-cubicweb, cubicweb-ctl, cubicweb-blog

.. Note::

    You may also require extra Debian packages such as::

        gettext, graphviz

Windows or Mac OS X users must install |cubicweb| from source (see
:ref:`SourceInstallation` and :ref:`WindowsInstallation`).

You can also install those packages using pip in a virtualenv::

   virtualenv venv
   source venv/bin/activate
   pip install cubicweb[pyramid] cubicweb-blog

Then create and initialize your instance::

    cubicweb-ctl create blog myblog

The `blog` argument is the cube on which you want to base your instance and
`myblog` is the name of your instance.

.. Note::

   If you get an a permission error of this kind `OSError: [Errno 13]
   Permission denied: '/etc/cubicweb.d/myblog'`, read the :ref:`next section`.

You'll be asked a few questions, and you can keep the default answer for most of
them. The one question you'll have to think about is the database you'll want to
use for that instance. For a quick test, if you don't have `postgresql` installed
and configured (see :ref:`PostgresqlConfiguration`), it's highly recommended to
choose `sqlite` when asked for which database driver to use, since it has a much
simple setup (no database server needed).

Then, you need to setup the CubicWeb Pyramid interface, as document at
:ref:`pyramid_settings`.

One the process is completed (including database initialisation), you can start
your instance by using: ::

    cubicweb-ctl pyramid -D myblog

The `-D` option activates the debugging mode. Removing it will launch the instance
as a daemon in the background.

.. _AboutFileSystemPermissions:

About file system permissions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Unless you installed from sources, the above commands assume that you have root
access to the :file:`/etc/` directory. In order to initialize your instance as a
regular user, within your home directory, you can use the :envvar:`CW_MODE`
environment variable: ::

  export CW_MODE=user

then create a :file:`~/etc/cubicweb.d` directory that will hold your instances.

More information about how to configure your own environment is
available in :ref:`ResourceMode`.


Instance parameters
~~~~~~~~~~~~~~~~~~~

If you would like to change database parameters such as the database host or the
user name used to connect to the database, edit the `sources` file located in the
:file:`/etc/cubicweb.d/myblog` directory.

Then relaunch the database creation::

     cubicweb-ctl db-create myblog

Other parameters, like web server or emails parameters, can be modified in the
:file:`/etc/cubicweb.d/myblog/all-in-one.conf` file (or :file:`~/etc/cubicweb.d/myblog/all-in-one.conf` depending on your configuration.)

You'll have to restart the instance after modification in one of those files.

This is it. Your blog is functional and running. Visit http://localhost:8080 and enjoy it!