Skip to content

Commit

Permalink
📝(readme) update the README to container-native development
Browse files Browse the repository at this point in the history 
I added some explanation on the genèse of Richie and updated
all information to reflect the current status of the project.
I decided to keep the native installation procedure as an
alternative to remain inclusive of old fashion ways.
  • Loading branch information
@sampaccoud
sampaccoud committed May 17, 2018
1 parent 959eef5 commit 931e135
Show file tree
Hide file tree
Showing 6 changed files with 353 additions and 282 deletions.
205 changes: 84 additions & 121 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,185 +1,148 @@
# Installing FUN CMS
# Richie, a FUN CMS for Open edX

[![Greenkeeper badge](https://badges.greenkeeper.io/openfun/richie.svg)](https://greenkeeper.io/)

[![CircleCI](https://circleci.com/gh/openfun/richie/tree/master.svg?style=svg)](https://circleci.com/gh/openfun/richie/tree/master)

This document aims to list all needed steps to have a working `FUN CMS` installation on your laptop.
## Overview

A better approach is to use [`Docker`](https://docs.docker.com). To get started, you can read [explanations](docs/docker.md) on how `FUN CMS` uses Docker for development.
`Open edX` is a great tool for authoring (**Studio**), hosting and playing (**LMS**) interactive
online courses and MOOCs.

However, if you need to build a complete website with flexible content to aggregate your courses,
in several languages and from different sources, **you will soon need a CMS**.

## Installing a fresh server
For example, the [edx.org](https://www.edx.org) website is built on `Drupal` for content pages and
on [edX course discovery](https://github.com/edx/course-discovery) for the catalog.

### Version
At "France Université Numérique", we wanted to build a similar portal but with `Python` and
`Django`. That's why we built `Richie` on top of [DjangoCMS](https://www.django-cms.org), one of
the best CMS on the market, as a toolbox to easily create full fledged websites with a catalog of
online courses.

You need a `Ubuntu 16.04 Xenial Xerus` (the latest LTS version) fresh installation.
Among the features that `Richie` offers out of the box:

If you are using another operating system or distribution, you can use [`Vagrant`](https://docs.vagrantup.com/v2/getting-started/index.html) to get a running Ubuntu 16.04 server in seconds.
- multi-site and multi-lingual by default,
- advanced access rights and moderation,
- catalog of courses synchronized with one or more `Open edX` instances,
- search engine based on `Elasticsearch` and pre-configured to offer full-text queries,
multi-facetting, auto-complete,...
- flexible custom pages for courses, organizations, subjects, teachers (and their inter-relations),
- Extensible with any third-party `DjangoCMS` plugin or any third-party `Django` application.


### System update
## Architecture

Be sure to have fresh packages on the server (kernel, libc, ssl patches...):
post
```sh
sudo apt-get -y update
sudo apt-get -y dist-upgrade
```
`Richie` is a **container-native application** but can also be installed [on your machine]
(./docs/native_installation.md).

For development, the project is defined using a [docker-compose file](../docker-compose.yml) and
consists of 4 services:

## Database part
- **db**: the `Postgresql` database,
- **elasticsearch**: the search engine,
- **app**: the actual `DjangoCMS` project with all our application code,
- **node**: used for front-end related tasks, _i.e._ transpiling `TypeScript` sources, bundling
them into a JS package, and building the CSS files from Sass sources.

You must first install `postgresql`.
We provide alternative `Docker Compose` configurations for test, CI and production, but the
application can also be run with your favorite orchestrator. At France Université Numérique, we
deploy our applications on `OpenShift` using [`Arnold`](https://github.com/openfun/arnold).

```sh
// On Linux
sudo apt-get -y install postgresql-9.5

// On OS X
brew install postgresql@9.5
brew services start postgresql@9.5
// don't forget to add your new postgres install to the $PATH
```
## Getting started

`Postgresql` is now running.
First, make sure you have a recent version of Docker and
[Docker Compose](https://docs.docker.com/compose/install) installed on your laptop:

Then you can create the database owner and the database itself, using the `postgres` user:
```bash
$ docker -v
Docker version 1.13.1, build 092cba3

```sh
sudo -u postgres -i // skip this on OS X as the default install will use your local user
createuser funadmin -sP
$ docker-compose --version
docker-compose version 1.17.1, build 6d101fb
```

Note: we created the user as a superuser. This should only be done in dev/test environments.
Now, create the database with this user:
```sh
createdb richie -O funadmin -W
exit
```
## Elasticsearch
### Ubuntu
Download and install the Public Signing Key
$ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add -
You may need to install the apt-transport-https package on Debian before proceeding:
$ sudo apt-get install apt-transport-https
Save the repository definition to /etc/apt/sources.list.d/elastic-6.1.2.list:
$ echo "deb https://artifacts.elastic.co/packages/6.1.2/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-6.1.2.list
Update repository and install
$ sudo apt-get update
$ sudo apt-get install elasticsearch
$ sudo /etc/init.d/elasticsearch start
### OS X
$ brew install elasticsearch
## Application part
### Python and other requirements
We use `Python 3.5` which is the one installed by default in `Ubuntu 16.04`.
You can install it on OS X using the following commands. Make sure to always run `python3` instead of `python` and `pip3` instead of `pip` to ensure the correct version of Python (your homebrew install of 3) is used.
```
brew install python3
brew postinstall python3
```
⚠️ You may need to run the following commands with `sudo` but this can be avoided by assigning your
user to the `docker` group.

The easiest way to start working on the project is to use our `Makefile`:

### The virtualenv
$ make bootstrap

Place yourself in the application directory `app`:
This command builds the `app` container, installs front-end and back-end dependencies, builds the
front-end application and styles, and performs database migrations. It's a good idea to use this
command each time you are pulling code from the project repository to avoid dependency-related or
migration-related issues.

cd app
Now that your `Docker` services are ready to be used, start the full CMS by running:

We choose to run our application in a virtual environment.
$ make run

For this, we'll install `virtualenvwrapper` and add an environment:
You should be able to view the site at [localhost:8070](http://localhost:8070)

pip install virtualenvwrapper
Once the CMS is up and running, you can create a superuser account:

You can open a new shell to activate the virtualenvwrapper commands, or simply do:
$ make superuser

source $(which virtualenvwrapper.sh)

Then create the virtual environment for `richie`:
## Contributing

mkvirtualenv richie --no-site-packages --python=python3
This project is intended to be community-driven, so please, do not hesitate to get in touch if you
have any question related to our implementation or design decisions.

The virtualenv should now be activated and you can install the Python dependencies for development:
We try to raise our code quality standards and expect contributors to follow the recommandations
from our [handbook](https://openfun.gitbooks.io/handbook/content).

pip install -r requirements/dev.txt

The "dev.txt" requirement file installs packages specific to a dev environment and should not be used in production.
### Checking your code

We use strict flake8, pylint and black linters to check the validity of our backend code:

### Settings
$ make lint-back

Settings are defined in different files for each of the following environments:
We use strict tslint and prettier to check the validity of our frontend code:

- dev: settings for development on developpers' local environment,
- ci: settings used on the continuous integration platform,
- staging: settings for deployment to the staging environment,
- preprod: settings for deployment to the pre-production environment,
- prod: settings for deployment to the production environment.
$ make lint-front

The `dev` environment is defined as the default environment.

For development, you can add your own settings file named `local.py` to customize settings to your needs. It will be ignored by git.
### Running tests

### Frontend build
On the backend, we use pytest to run our test suite:

This projet is a hybrid that uses both Django generated pages and frontend JS code. As such, it includes a frontend build process that comes in two parts: JS & CSS.
$ make test-back

We need NPM to install the dependencies and run the build, which depends on a version of Nodejs specified in `.nvmrc`. See [the repo](https://github.com/creationix/nvm) for instructions on how to install NVM. To take advantage of `.nvmrc`, run this in the context of the repository:
On the frontend, we use karma to run our test suite:

nvm install
nvm use
$ make test-front

As a prerequisite to running the frontend build for either JS or CSS, you'll need to [install yarn](https://yarnpkg.com/lang/en/docs/install/) and download dependencies _via_:

yarn install
### Running migrations

- JS build
The first time you start the project with `make bootstrap`, the `db` container automatically
creates a fresh database named `richie` and performs database migrations. Each time a new
**database migration** is added to the code, you can synchronize the database schema by running:

npm run build
$ make migrate

- CSS build

This will compile all our SCSS files into one bundle and put it in the static folder we're serving.
### Handling new dependencies

npm run sass
Each time you add new front-end or back-end dependencies, you will need to rebuild the
application. We recommend to use:

### Run server
$ make bootstrap

Make sure your database is up-to-date before running the application the first time and after each modification to your models:

python manage.py migrate
### To go further

You can now create a superuser account:
To see all available commands, run:

python manage.py createsuperuser
$ make

Run the tests
See our [tips and tricks](./docs/docker_development.md) for development with Docker

python manage.py test

You should now be able to start Django and view the site at [localhost:8000](http://localhost:8000)
## License

python manage.py runserver
This work is released under the MIT License (see [LICENSE](./LICENSE)).
0 docs/CSS.md → docs/css.md
View file
File renamed without changes.
0 docs/django-react-interop.md → docs/django_react_interop.md
View file
File renamed without changes.
Loading

0 comments on commit 931e135

Please sign in to comment.