Chill-project/chill-bundles
6
0
Fork 0
mirror of https://gitlab.com/Chill-Projet/chill-bundles.git synced 2025-06-12 13:24:25 +00:00
Code Issues Actions Projects Releases Wiki Activity

Merge pull request 2

Browse Source
This commit is contained in:
Julien Fastré 2015-07-02 23:29:48 +02:00
commit 1f408ce758
12 changed files with 295 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
source/bundles/custom-fields.rst
View File

@ -6,6 +6,8 @@
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _custom-fields-bundle:
Custom fields bundle
====================
@ -42,7 +44,7 @@ Some entities needs a **default** custom fields group. For instance, the default
In the future of the `person bundle`, other custom fields group will be added in forms accessible from the menu, allowing users to completely customize and separate their entities.
Allow custom fields on a entity
--------------------------------
-------------------------------
As a developer, you must allow your users to add custom fields on your entities.
@ -126,7 +128,7 @@ Add those file under `chill_custom_fields` section :
* The class, which is a full FQDN class path
Automatically, in DependencyInjection/Extension class
""""""""""""""""""""""""""""""""""""""""""""""""""""""
"""""""""""""""""""""""""""""""""""""""""""""""""""""
This is the preferred way for declaring customizable classes.
@ -262,7 +264,7 @@ In the `PrependExtensionInterface::prepend` function, the options key will be ad
Note that `custom_fields_group_linked_custom_fields` does not create any input on `CustomFieldsGroup` creation : there aren't any fields associated with the custom fields just after the group creation... You have to add custom fields and associate them with the newly created group to see them appears.
Rendering custom fields in a template
--------------------------------------
-------------------------------------
Two function are available :
@ -310,7 +312,7 @@ Examples:
Custom Fields's form
---------------------
--------------------
You should simply use the 'custom_field' type in a template, with the group you would like to render in the `group` option's type.
@ -377,7 +379,7 @@ Example :
Development tips
-----------------
----------------
If you want to test the rendering of a custom fields group, you may use this method :

4
source/bundles/main.rst
View File

@ -5,7 +5,9 @@
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _main-bundle:
Main bundle
###########

8
source/bundles/person.rst
View File

@ -5,7 +5,9 @@
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _person-bundle:
Person bundle
#############
@ -23,12 +25,12 @@ Entities provided
Search terms
*************
************
The class `Chill\PersonBundle\Search\PersonSearch` provide the search module.
Domain
=======
======
The search upon "person" is provided by default. The `@person` domain search may be omitted.

4
source/bundles/report.rst
View File

@ -5,7 +5,9 @@
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _report-bundle:
Report bundle
#############

4
source/development/create-a-new-bundle.rst
View File

@ -6,8 +6,10 @@
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _create-new-bundle:
Create a new bundle
********************
*******************
Create your own bundle is not a trivial task.

8
source/installation/index.rst
View File

@ -12,7 +12,7 @@
Free Documentation License".
Instructions about installation
################################
###############################
You will learn here :
@ -20,7 +20,11 @@ You will learn here :
:maxdepth: 2
How to install the software <installation.rst>
Add new bundles to your installation <install_new_bundles.rst>
Update Chill <update_chill.rst>
Add bundles to your installation <install_additional_bundles.rst>
Uninstall Chill <uninstall_chill.rst>
Install a PosgresSql server <install_postgres_server.rst>
Install production webserver <install_production_webserver.rst>
.. todo::

50
source/installation/install_additional_bundles.rst Normal file
View File

@ -0,0 +1,50 @@
.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _install-additional-bundles:
Install additional bundles
##########################
A basic installation of Chill include four bundles:
- :ref:`main-bundle`
- :ref:`person-bundle`
- :ref:`report-bundle`
- :ref:`custom-fields-bundle`
but you can add as many as needed by your project, and if the bundle does not exists yet, you can create a new one, see :ref:`create-new-bundle` .
In Chill you are free to do what is most suitable for your activity, so let's go into details on how to add an existing bundle.
We will add the bundle 'icpc2' that set `icpc code <https://en.wikipedia.org/wiki/International_Classification_of_Primary_Care>`_ available as custom field.
.. todo::
Add description of the bundle
Open your terminal let composer do the magic for you:
.. code-block:: bash
cd path/to/your/directory
composer require chill-main/icpc2
As composer ends its task, it could notify you that `Some migration files have been imported.
In this case You should run `php app/console doctrine:migrations:status` and/or `php app/console doctrine:migrations:migrate` to apply them to your DB.`
So just do it:
.. code-block:: bash
php app/console doctrine:migrations:migrate
.. note::
The following has to be automated:
Finally we should modify the AppKernel.php file adding `new Chill\\Icpc2Bundle\\ChillIcpc2Bundle(),` in the $bundle array as described `in the symfony documentation <http://symfony.com/doc/current/cookbook/bundles/installation.html#b-enable-the-bundle>`_.

26
source/installation/install_postgres_server.rst Normal file
View File

@ -0,0 +1,26 @@
.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _install-postgres-server:
Install PostgresSql server
##########################
.. todo::
the section "Install PostresSql database" must be written. Help appreciated :-)
.. note::
To avoid installation and configuration of a postgresql server, you may use `our docker image <https://registry.hub.docker.com/u/chill/database/>`_ to start and configure a database as decribed in the basic installation chapter.
This solution can be used also in a production environment.
.. note::
Installing unaccent extension on ther server is possible with the package `postgresql-contrib-9.x` (replace 9.x with your server version). The extension may be enabled with running `CREATE EXTENSION unaccent;` in the database, with a superuser account.

9
source/installation/install_new_bundles.rst → source/installation/install_production_webserver.rst
View File

@ -6,11 +6,12 @@
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _install-new-bundles:
.. _install-production-webserver:
Install new bundles to your installation
########################################
Install production webserver
############################
.. todo::
the section "install new bundles" must be written. Help appreciated :-)
the section "Install production webserver" must be written. Help appreciated :-)

194
source/installation/installation.rst
View File

@ -15,76 +15,30 @@ Installation
Basic installation
``````````````````
Chill is written in PHP and use the `symfony framework`_. We take advantages of all the framework's feature, and installation should be as simple as installing symfony.
We are going to describe a basic installation on Unix systems (Unix, Mac OS). Windows installation has not been tested.
Requirements
------------
Server requirements
^^^^^^^^^^^^^^^^^^^^
* a postgresql database, with the `*unaccent* extension`_ enabled. The minimum version is postgresql 9.4. Alternatively, you can use `the docker image provided <https://registry.hub.docker.com/u/chill/database/>`_ (see notes above)
* php 5.5
* If you run Chill in production mode, you should also install a web server (apache, ngnix, ...). We may use php built-in server for testing and development.
Within this documentation, we are going to describe installation on Unix systems (Unix, Mac OS). Windows installation has not been tested.
You won't need any web server for setting up an instance for a demonstration or development.
.. note::
Installing unaccent extension on ther server is possible with the package `postgresql-contrib-9.x` (replace 9.x with your server version). The extension may be enabled with running `CREATE EXTENSION unaccent;` in the database, with a superuser account.
.. note::
To avoid installation and configuration of a postgresql server, you may use `our docker image <https://registry.hub.docker.com/u/chill/database/>`_ to start and configure a database.
After `docker installation <http://docs.docker.com/>`_, run :
.. code-block:: bash
sudo docker run -P --name=chill_db chill/database
This will download the chill/database image and start a new docker instance with the name `chill_db` and export the postgresql port `5432` on another random local port.
In a new terminal, run
.. code-block:: bash
sudo docker port chill_db 5432
This command will show on which port the docker container is listening, on your localhost. During the part :ref:`create-your-project` this is the value to be used to fill the field 'database_port'.
Client requirements
^^^^^^^^^^^^^^^^^^^
Chill is accessible through a web browser. Currently, we focus our support on `Firefox`_, because firefox is open source, cross-platform, and very well active. The software should work with other browser (Chromium, Opera, ...) but some functionalities might break.
Preparation
-----------
Server requirements
^^^^^^^^^^^^^^^^^^^
You will need those informations :
* a postgresql database, with the `*unaccent* extension`_ enabled. The minimum version is postgresql 9.4. You can use `the docker image provided <https://registry.hub.docker.com/u/chill/database/>`_. Using the docker image is also a solution for production site. Alternatively you can install a PosgresSql server see :ref:`install-postgres-server`.
* PHP 5.5.
* Composer.
* If you run Chill in production mode, you should also install a web server (apache, ngnix, ...) see :ref:`install-production-webserver`. For this basic installation meant for testing and/or development, we will make it simplier using the php built-in server.
* The information to access to your database: host, port, database name, and your credentials (username and password) ;
* a random string, which will be use to improve entropy in security. Choose anything you want (random character, your father's birthplace, ...).
If you have installed the docker database your information should be:
- database_host: 127.0.0.1
- database_port: [see above]
- database_name: postgres
- database_user: postgres
- database_password: postgres
- locale: fr
Installation
------------
Chill is installed with `composer`_.
Let's start by installing composer as it is needed to create and update our Chill project.
Install composer
^^^^^^^^^^^^^^^^
""""""""""""""""
.. note::
If you do not know composer, it is a good idea to have a glance at `the composer documentation`_
@ -95,25 +49,95 @@ Install composer on your system :
curl -sS https://getcomposer.org/installer | php
Move composer.phar to your system
"""""""""""""""""""""""""""""""""
Install composer.phar globally
""""""""""""""""""""""""""""""
.. note::
This part is not necessary, but this will be more convenient for the process. If you do not want to install composer on your system, you will have to replace the commands `composer` by `php composer.phar`.
This part is not mandatory, if you do not want to install composer globally, you will have to replace in the commands of this tutorial `composer` by `php composer.phar`.
Install composer globally on you system will made the installation process more convenient. To do this, simply run
Install composer globally on you system will made the installation process easier. To do this, simply run
.. code-block:: bash
sudo mv composer.phar /usr/local/bin/composer
Then, just run `composer` instead of `php composer.phar`
sudo chmod +x /usr/local/bin/composer
You can test the installation by running `which composer` or `composer`: those command should not raise any error.
.. note::
See `the composer introduction`_ to learn how to install composer on Mac OS X and Windows
The docker database
"""""""""""""""""""
Let's continue now by installing and configuring the docker database.
You will find all details concerning the installation of docker on their official site looking for your OS into the menu `Install/Docker Engine <http://docs.docker.com/>`_.
Once docker is installed, run :
.. code-block:: bash
sudo docker run -P --name=chill_db chill/database
This will download the chill/database image and start a new docker instance with the name `chill_db` and export the postgresql port `5432` on another random local port.
The db will start in your terminal. In another terminal, you can check if the docker database is running and showing the exposed port with the following command:
.. code-block:: bash
sudo docker ps
>>>> CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
>>>> 08bbb62bd5e8 chill/database "/docker-entrypoint. 6 days ago Up 5 hours 0.0.0.0:32768->5432/tcp chill_db
You can start and stop the container it via:
.. code-block:: bash
sudo docker start chill_db
>>>> chill_db
sudo docker stop chill_db
>>>> chill_db
Installation
------------
Chill is installed with `composer`_.
.. _preparation:
Preparation
^^^^^^^^^^^
Before creating your project, make sure that you know the following information :
* how to access to your database: host, port, database name, and your credentials (username and password) ;
* a random string, which will be used to improve entropy in security. Choose anything you want (random character, your father's birthplace, ...).
.. note::
**If you have installed the docker database:**
Open a terminal and run
.. code-block:: bash
sudo docker port chill_db 5432
This command will show on which port the docker container is listening, on your localhost.
This is the value to be used to fill the field 'database_port' hereafter.
Your information should be:
- database_host: 127.0.0.1
- database_port: result of the command hereabove.
- database_name: postgres
- database_user: postgres
- database_password: postgres
- locale: fr
.. _create-your-project:
Create your project
@ -123,8 +147,7 @@ Create your Chill project using composer:
.. code-block:: bash
php composer.phar create-project chill-project/standard \
path/to/your/directory --stability=dev
composer create-project chill-project/standard path/to/your/directory --stability=dev
You should, now, move your cursor to the new directory
@ -133,7 +156,7 @@ You should, now, move your cursor to the new directory
cd path/to/your/directory
.. note::
Until now, the stability of the project is set to "dev". Do not forget this argument, or composer will fail to download and create the project.
Until now, the stability of the project is set to "dev". Do not forget this argument, or composer will fail to download and create the project.
Composer will download `the standard architecture`_ and ask you a few question about how to configure your project.
@ -143,9 +166,10 @@ Composer will download `the standard architecture`_ and ask you a few question a
* `database_user` : the username to reach your database
* `database_password` : your username's password
* `locale`: the language, as iso code. Until now, only fr is supported
* `secret`: the secret string you prepared (see "preparation")
* `secret`: the secret string you prepared (see :ref:`preparation`)
You may accept the default parameters of `debug_toolbar`, `debug_redirects` and `use_assetic_controller` for a demonstration installation. For production, set them all to `false`.
You may accept the default parameters of `debug_toolbar`, `debug_redirects` and `use_assetic_controller` for a demonstration installation.
For production, set them all to `false`.
.. note::
@ -163,7 +187,7 @@ You may accept the default parameters of `debug_toolbar`, `debug_redirects` and
`php app/console doctrine:migrations:status` and/or
`php app/console doctrine:migrations:migrate` to apply them to your DB.
We will proceed to this step some steps further. See :ref:`create-database-schema`.
We will proceed this step a bit later. See :ref:`create-database-schema`.
Check your requirements
^^^^^^^^^^^^^^^^^^^^^^^
@ -194,38 +218,26 @@ SQL queries will be printed into your console.
Populate your database with basic information
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once your database schema is ready, you should populate your database with some basic information. Those are provided through scripts and might depends from the bundle you choose to install (see :ref:`install-new-bundles`)
Once your database schema is ready, you should populate your database with some basic information. Those are provided through scripts and might depends from the bundle you choose to install (see :ref:`install-additional-bundles`)
The main bundle require two scripts to be executed :
.. code-block:: bash
php app/console chill:main:countries:populate
php app/console chill:main:languages:populate
php app/console doctrine:fixtures:load
Those will populate database, respectively, with countries (using ISO declaration) and languages (using, also, ISO informations).
Those will populate database, respectively, with basic dummy data, countries (using ISO declaration) and languages (using, also, ISO informations).
Building CSS (optionnal)
^^^^^^^^^^^^^^^^^^^^^^^^
For this step, npm must be installed.
A build version of the needed CSS file is provided within the main bundle `Resources/public/css/chillmain.css`. For rebuilding it :
Preparing assets
^^^^^^^^^^^^^^^^
You have to dump assets into the web directory. Even if the command should be run by Composer, you may run it manually :
.. code-block:: bash
#in the main bundle directory ( vendor/chill-project/main/ )
cd vendor/chill-project/main/Resources/
npm install grunt
Go back to your project root before doing next step
.. code-block:: bash
cd path/to/your/directory
php app/console assetic:dump
php app/console assets:install
Launch your server
@ -237,7 +249,11 @@ If everything was fine, you are able to launch your built-in server :
php app/console server:run
Your server should now be available at `http://localhost:8000`. Type this address on your browser and you should see the homepage.
Your server should now be available at `http://localhost:8000`. Type this address on your browser and you should see the homepage.
The default login is 'center a_social' with password 'password'.
Have fun exploring Chill.
.. _the composer documentation: https://getcomposer.org/doc/
.. _the composer introduction: https://getcomposer.org/doc/00-intro.md

34
source/installation/uninstall_chill.rst Normal file
View File

@ -0,0 +1,34 @@
.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _uninstall-chill:
Uninstall Chill
```````````````
.. todo::
the section "Uninstall Chill" must be written. Help appreciated :-)
.. _uninstall-docker-database:
Uninstall the docker database
-----------------------------
.. todo::
the section "Uninstall the docker database" must be written. Help appreciated :-)
.. _uninstall-application:
Uninstall the application
-------------------------
.. todo::
the section "Uninstall the application" must be written. Help appreciated :-)

48
source/installation/update_chill.rst Normal file
View File

@ -0,0 +1,48 @@
.. Copyright (C) 2014 Champs Libres Cooperative SCRLFS
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
.. _update-chill:
Update Chill
############
Updating the application is very simple, thanks to the use of composer.
.. code-block:: bash
cd path/to/your/directory
composer update
Composer allow to control strictly the versions to be used in the application.
This allow to manage a production server, a staging one and a developpement one.
For the production one, define very precisely the versions of each component in the `composer.json` file at the root of the application and require only `stable` versions.
In this situation even if an update of composer is launched, the sources will not be modified.
For the staging and development one, let open choices to the versions or accept development versions and using `composer update` will automatically update the selected modules.
Once validated at staging level they can be sent in production re-precising the latest accepted versions.
.. note::
It is advisable to keep the version of composer up to date. To do that, just launch the following command in a terminal.
.. code-block:: bash
composer self-update
If this update create troubles (which doesn't happen often) you can always undo this update running:
.. code-block:: bash
composer self-update --rollback
See the `the composer documentation`_ for all details.
.. _the composer documentation: https://getcomposer.org/doc/