diff -r c1d04b2fa8c6 -r f756ead5746a doc/book/en/03-02-create-instance.en.txt --- a/doc/book/en/03-02-create-instance.en.txt Tue Nov 18 11:51:22 2008 -0800 +++ b/doc/book/en/03-02-create-instance.en.txt Tue Nov 18 15:06:33 2008 -0800 @@ -1,127 +1,124 @@ .. -*- coding: utf-8 -*- -=================================== -Creation de votre premiere instance -=================================== +=============================== +Creation of your first instance +=============================== + +What is an instance? +==================== + +A `CubicWeb` instance is a directory in ``~/etc/cubicweb.d`` +which enables us to run a web application. An instance is based on +one or more cubes. + +An instance is a container that refers to cubes and configuration +parameters for your web application. + +We recommand not to define schema, entities or views in the instance +file system itself but in the cube, in order to maintain re-usability of +entities and their views. We strongly recommand to develop cubes which +could be used in other instances (modular approach). -Qu'est-ce qu'une instance? -========================== +What is a cube? +=============== -Une instance CubicWeb consiste en un dossier situe dans ``~/etc/cubicweb.d`` -qui permettra de lancer une application web. Une instance est cree a partir -d'un ou plusieurs cubes. - -Nous recommandons de ne pas definir de schema, entites ou vues dans l'instance -meme si cela est possible dans un but de re-utilisabilite des entities et de leurs -vues. Nous conseillons plutot de developper des cubes qui pourront par la suite -etre utilises dans d'autres instances (approche modulaire). +A cube defines entities, their views, their schems and workflows +in an independant directory located in ``/path/to/forest/cubicweb/cubes/``. -L'instance n'est qu'un conteneur referrant a des cubes et a des parametres -des configuration de l'application web. - -Qu'est-ce qu'un cube? -===================== +When an instance is created, you list one or more cubes that your instance +will use. Use a cube means having the entities defined in your cube's schema +available in your instance as well as their views and workflows. -Un cube definit des entities, leur vues, leur schemas et leur workflow -dans un repertoire independant situe dans ``/path/to/forest/cubicweb/cubes/``. - -Lors de la creation d'une instance, vous avez la possibilite de lister -le ou les cubes que votre instance va utiliser. Utiliser un cube signifie -avoir a disposition dans votre instance les entites definies dans le schema -de votre cube ainsi que les vues et les workflows. +.. note:: + The commands used below are more detailled in the section dedicated to + :ref:`cubicweb-ctl`. -.. note:: - Les commandes utilisees ci-apres sont detaillees dans la section - dediee a :ref:`cubicweb-ctl`. - +Create a cube +============= -Création d'un cube -================== - -Commençons par créer un squelette qui nous servira de base au développement de -notre cube ou application :: +Let's start by creating the cube environment in which we will develop :: cd ~/hg - cubicweb-ctl newtemplate moncube + cubicweb-ctl newcube mycube - # répondre aux questions + # answer questions hg init moncube - cd moncube + cd mycube hg add . hg ci -A partir de là si tout va bien, votre cube devrait être affiché par -`cubicweb-ctl list` dans la section *Available components*, si ce n'est pas le cas -revoir la section :ref:`ConfigurationEnv`. +If all went well, you should see the cube you just create in the list +returned by `cubicweb-ctl list` in the section *Available components*, +and if it is not the case please refer to :ref:`ConfigurationEnv`. + +To use a cube, you have to list it in the variable ``__use__`` +of the file ``__pkginfo__.py`` of the instance. +This variable is used for the instance packaging (dependencies +handled by system utility tools such as APT) and the usable cubes +at the time the base is created (import_erschema('MyCube') will +not properly work otherwise). + +Instance creation +================= + +Now that we created our cube, we can create an instance to view our +application in a web browser. To do so we will use a `all-in-on` +configuration to simplify things :: + + cubicweb-ctl create -c all-in-one mycube myinstance + +.. note:: + Please note that we created a new cube for a demo purpose but + you could have use an existing cube available in our standard library + such as blog or person by example. + +A serie 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 user/psswd is requested to access the database +please use the login you create at the time you configured the database +(:ref:`ConfigurationPostgres`). + +It is important to distinguish here the user used to access the database and +the user used to login to the cubicweb application. When a `CubicWeb` application +starts, it uses the login/psswd for the database to get the schema and handle +low transaction [FIXME - bas niveau]. But, when ``cubicweb-ctl create`` asks for +a manager login/psswd of `CubicWeb`, it refers to an application user you will +use during the development to administrate your web application. It will be +possible, later on, to create others users for your final web application. + +When this command is completed, the definition of your instance is +located in *~/etc/cubicweb.d/moninstance/*. To launch it, you just type :: + + cubicweb-ctl start -D myinstance + +The option `-D` specify the *debug mode* : the instance is not running in +server mode and does not disconnect from the termnial, 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/psswd 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... -Pour utiliser un cube, il faut le mentionner dans la variable -__use__ du fichier __pkginfo__ de l'application. Cette variable -contrôle à la fois le packaging de l'application (dépendances gérées -par les utilitaires système comme les outils APT) et les composants -effectivement utilisables lors de la création de la base -(import_erschema('Moncomposant') ne fonctionne pas sinon). - -Création d'une instance de développement -======================================== - -Maintenant que nous avons notre squelette de modèle, on peut en créer une -instance afin de voir ce que tout ça donne dans un simple navigateur web. -Nous allons utiliser une configuration `all-in-one` afin de simplifier les -choses :: +Usage of `cubicweb-liveserver` +------------------------------ - cubicweb-ctl create -c all-in-one moncube moninstance - -Une série de questions vont être posées, la réponse par défaut est généralement -suffisante. Vous pourrez de toute façon modifier la configuration par la suite -en éditant les fichiers générés. Lorsqu'un login/mot de passe d'accès au sgbd -vous est demandé, il est recommandé d'utiliser l'utilisateur créé lors de la -:ref:`ConfigurationPostgres`. - -Il est important de distinguer ici l'utilisateur utilisé pour accéder au sgbd, -et l'utilisateur utilisé pour s'authentifier dans l'application cubicweb. Lorsque -l'application cubicweb démarre, elle utilise le login/mot de passe sgdb pour -récupérer le schéma et gérer les transactions bas-niveau. En revanche, lorsque -`cubicweb-ctl create` vous demande un login/mot de passe `manager` pour cubicweb, il -s'agit d'un utilisateur qui sera créé dans l'application `cubicweb` pour pouvoir -s'y connecter dans un premier temps et l'administrer. Il sera par la suite possible -de créer des utilisateurs différents pour l'application. +To quickly test a new cube, you can also use the script `cubicweb-liveserver` +which allows to create an application in memory (use of SQLite database by +default) and make it accessible through a web server :: -A l'issue de cette commande, la définition de votre instance se trouve dans -*~/etc/cubicweb.d/moninstance/*. Pour la lancer, il suffit de taper :: - - cubicweb-ctl start -D moninstance - -L'option `-D` indique le *debug mode* : l'instance ne passe pas en mode serveur -et ne se déconnecte pas du terminal, ce qui simplifie le dépannage en cas de non -démarrage de l'instance. Vous pouvez ensuite allez voir ce que ça donne en -pointant votre navigateur sur l'url `http://localhost:8080` (le n° de port -dépend de votre configuration). Pour vous authentifier vous pouvez utiliser le -login/mot de passe administrateur que vous avez spécifié lors de la création de -l'instance. - -Pour arrêter l'instance, un Ctrl-C dans la fenêtre où vous l'avez lancé -suffit. Si l'option `-D` a été omise, il faut taper :: - - cubicweb-ctl stop moninstance + cubicweb-ctl live-server mycube -Voilà, tout est en place pour démarrer le développement du modèle... - - -Utilisation de cubicweb-liveserver ----------------------------------- +or by using an existing database (SQLite or Postgres):: -Afin de tester rapidement un nouveau cube, on peut également -utiliser le script `cubicweb-liveserver` qui permet de créer une -application en mémoire (utilisant une base de données SQLite par -défaut) et la rendre accessible via un serveur web:: + cubicweb-ctl live-server -s myfile_sources mycube - cubicweb-ctl live-server moncomposant - -ou bien, pour utiliser une base de données existante (SQLite ou postgres):: - - cubicweb-ctl live-server -s monfichier_sources moncomposant -