5. Creation of your first instance

5.1. Instance creation

Now that we created a cube, we can create an instance and access it via a web browser. We will use a all-in-one configuration to simplify things

cubicweb-ctl create -c all-in-one mycube myinstance


Please note that we created a new cube for a demo purposes but you could have used an existing cube available in our standard library such as blog or person for example.

A series of questions will be prompted to you, the default answer is usually sufficient. You can anyway modify the configuration later on by editing configuration files. When a login/password are requested to access the database please use the credentials you created at the time you configured the database (PostgreSQL).

It is important to distinguish here the user used to access the database and the user used to login to the cubicweb instance. When an instance starts, it uses the login/password for the database to get the schema and handle low level transaction. But, when cubicweb-ctl create asks for a manager login/psswd of CubicWeb, it refers to the user you will use during the development to administrate your web instance. It will be possible, later on, to use this user to create other users for your final web instance.

5.2. Instance administration

5.2.1. start / stop

When this command is completed, the definition of your instance is located in ~/etc/cubicweb.d/myinstance/*. To launch it, you just type

cubicweb-ctl start -D myinstance

The option -D specifies the debug mode : the instance is not running in server mode and does not disconnect from the terminal, which simplifies debugging in case the instance is not properly launched. You can see how it looks by visiting the URL http://localhost:8080 (the port number depends of your configuration). To login, please use the cubicweb administrator login/password you defined when you created the instance.

To shutdown the instance, Crtl-C in the terminal window is enough. If you did not use the option -D, then type

cubicweb-ctl stop myinstance

This is it! All is settled down to start developping your data model...


The output of cubicweb-ctl start -D myinstance can be overwhelming. It is possible to reduce the log level with the –loglevel parameter as in cubicweb-ctl start -D myinstance -l info to filter out all logs under info gravity.

5.2.2. upgrade

A manual upgrade step is necessary whenever a new version of CubicWeb or a cube is installed, in order to synchronise the instance’s configuration and schema with the new code. The command is:

cubicweb-ctl upgrade myinstance

A series of questions will be asked. It always starts with a proposal to make a backup of your sources (where it applies). Unless you know exactly what you are doing (i.e. typically fiddling in debug mode, but definitely NOT migrating a production instance), you should answer YES to that.

The remaining questions concern the migration steps of CubicWeb, then of the cubes that form the whole application, in reverse dependency order.

In principle, if the migration scripts have been properly written and tested, you should answer YES to all questions.

Somtimes, typically while debugging a migration script, something goes wrong and the migration fails. Unfortunately the databse may be in an incoherent state. You have two options here:

  • fix the bug, restore the database and restart the migration process from scratch (quite recommended in a production environement)
  • try to replay the migration up to the last successful commit, that is answering NO to all questions up to the step that failed, and finish by answering YES to the remaining questions.

Table Of Contents

Previous topic

4. cubicweb-ctl tool

Next topic

6. Configure an instance