doc/tutorials/base/blog-in-five-minutes.rst
author Laurent Peuch <cortex@worlddomination.be>
Tue, 12 Feb 2019 14:48:52 +0100
changeset 12363 72fced7549e6
parent 10491 c67bcee93248
child 12379 04348101688a
permissions -rw-r--r--
[doc] improve blog tutorial first steps and explain common errors
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
     1
.. -*- coding: utf-8 -*-
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
     2
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
     3
.. _TutosBaseBlogFiveMinutes:
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
     4
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2174
diff changeset
     5
Get a blog running in five minutes!
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2174
diff changeset
     6
-----------------------------------
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
     7
6833
8fe4b003c1bc [doc] some ReST syntax fixes
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5432
diff changeset
     8
For Debian or Ubuntu users, first install the following packages
8fe4b003c1bc [doc] some ReST syntax fixes
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5432
diff changeset
     9
(:ref:`DebianInstallation`)::
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    10
1441
8e7a99cbce3c [doc] Short down the `blog running in less ten nimutes` section to remove duplicated content.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents: 1439
diff changeset
    11
    cubicweb, cubicweb-dev, cubicweb-blog
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    12
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    13
Windows or Mac OS X users must install |cubicweb| from source (see
6833
8fe4b003c1bc [doc] some ReST syntax fixes
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5432
diff changeset
    14
:ref:`SourceInstallation` and :ref:`WindowsInstallation`).
4431
e597e0ca67cd Updated CW tutorial.
Adrien Chauve <adrien.chauve@logilab.fr>
parents: 4143
diff changeset
    15
2175
16d3c37c5d28 [doc] improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 2174
diff changeset
    16
Then create and initialize your instance::
2172
cf8f9180e63e delete-trailing-whitespace
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 1715
diff changeset
    17
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    18
    cubicweb-ctl create blog myblog
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    19
12363
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    20
The `blog` argument is the cube on which you want to base your instance and
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    21
`myblog` is the name of your instance.
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    22
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    23
.. Note::
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    24
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    25
   If you get an a permission error of this kind `OSError: [Errno 13]
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    26
   Permission denied: '/etc/cubicweb.d/myblog'`, read the :ref:`next section`.
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    27
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    28
You'll be asked a few questions, and you can keep the default answer for most of
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    29
them. The one question you'll have to think about is the database you'll want to
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    30
use for that instance. For a quick test, if you don't have `postgresql` installed
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    31
and configured (see :ref:`PostgresqlConfiguration`), it's highly recommended to
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    32
choose `sqlite` when asked for which database driver to use, since it has a much
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    33
simple setup (no database server needed).
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    34
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    35
One the process is completed (including database initialisation), you can start
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    36
your instance by using: ::
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    37
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    38
    cubicweb-ctl start -D myblog
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    39
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    40
The `-D` option activates the debugging mode. Removing it will launch the instance
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    41
as a daemon in the background, and ``cubicweb-ctl stop myblog`` will stop
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    42
it in that case. 
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    43
12363
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    44
.. _AboutFileSystemPermissions:
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    45
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    46
About file system permissions
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    47
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4143
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    48
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    49
Unless you installed from sources, the above commands assume that you have root
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    50
access to the :file:`/etc/` directory. In order to initialize your instance as a
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    51
regular user, within your home directory, you can use the :envvar:`CW_MODE`
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    52
environment variable: ::
4143
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    53
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    54
  export CW_MODE=user
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    55
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    56
then create a :file:`~/etc/cubicweb.d` directory that will hold your instances.
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    57
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    58
More information about how to configure your own environment is
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    59
available in :ref:`ResourceMode`.
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    60
4143
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    61
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    62
Instance parameters
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    63
~~~~~~~~~~~~~~~~~~~
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    64
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    65
If you would like to change database parameters such as the database host or the
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    66
user name used to connect to the database, edit the `sources` file located in the
6833
8fe4b003c1bc [doc] some ReST syntax fixes
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 5432
diff changeset
    67
:file:`/etc/cubicweb.d/myblog` directory.
4143
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    68
5432
ee246e1813c6 [doc] various small improvements
Nicolas Chauvat <nicolas.chauvat@logilab.fr>
parents: 5253
diff changeset
    69
Then relaunch the database creation::
4143
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    70
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    71
     cubicweb-ctl db-create myblog
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    72
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    73
Other parameters, like web server or emails parameters, can be modified in the
12363
72fced7549e6 [doc] improve blog tutorial first steps and explain common errors
Laurent Peuch <cortex@worlddomination.be>
parents: 10491
diff changeset
    74
:file:`/etc/cubicweb.d/myblog/all-in-one.conf` file (or :file:`~/etc/cubicweb.d/myblog/all-in-one.conf` depending on your configuration.)
4143
e6d936eef7aa [mq]: doc
Charles Hébert
parents: 2175
diff changeset
    75
6835
87e2641d75f7 [doc] major rework of the simple blog tutorial
Sylvain Thénault <sylvain.thenault@logilab.fr>
parents: 6833
diff changeset
    76
You'll have to restart the instance after modification in one of those files.
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    77
6837
7562418985ef tutorial proof reading
Alexandre Fayolle <alexandre.fayolle@logilab.fr>
parents: 6835
diff changeset
    78
This is it. Your blog is functional and running. Visit http://localhost:8080 and enjoy it!
1210
47a3eb4bbe66 [doc] Adds a short section on how to launch a blog based on the packages cubicweb and cubicweb-blog.
Sandrine Ribeau <sandrine.ribeau@logilab.fr>
parents:
diff changeset
    79