coldcms 0.2.10

A CMS optimized for low consumption

Goal

A fully functional CMS optimized for low consumption.

Read blog posts about this.

Benchmark

Benchmark details to Coldcms

Description

ColdCMS is a Django project based on Wagtail CMS and Bulma CSS framework.

The admin can edit websites through an intuitive and user-friendly interface. Different types of pages are pre-designed, making it possible to have a nice-looking website without spending hours on it.

ColdCMS is especially designed for people who want to reduce the impact of their use of digital technologies on the environnement.

The client website consists of static pages, built with Wagtail bakery. The website pages are generated and updated when necessary (e.g. when the admin publishes or modifies content).

Among other optimizations, the size of CSS files is reduced and unused CSS code is removed, using PurgeCSS and clean-css.

ColdCMS supports Python >= 3.6.

How to use ColdCMS?

You have access to a ColdCMS instance and you want to create a website

You can find the user documentation here:

• English documentation

• Documentation en français

You want to install ColdCMS

You have two options: docker installation or manual installation.

Docker installation

You will need docker-compose and docker with a running daemon.

We provide a sample docker/docker-compose.yml file. Feel free to modify it for your needs.

cd docker && docker-compose up

Here are some env variables that you might want to change:

• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB see https://github.com/docker-library/docs/blob/master/postgres/README.md#environment-variables

• DB_URL, the database connection URL, see https://github.com/jacobian/dj-database-url#url-schema

• SECRET_KEY, the Django SECRET_KEY, it should be a private, 40-character long randomly-generated string

• ALLOWED_HOSTS, the coma-separated list of hosts allowed to serve your application, corresponds to the Django ALLOWED_HOSTS

You can then create an admin user which will have access to http://localhost/admin

docker exec -it docker_backend_1 python3 manage.py createsuperuser

Manual installation

1. Choose a database

We recommend using PostgreSQL, but you can also use the default SQLite (no setup required). If you choose to use PostgreSQL take note of the host, port, database, user, and password you’re using.

2. Install the backend part of ColdCMS

The backend is used to modify your website, it’s located on https://your-site.tld/admin

Download the latest release available here: https://gitlab.com/hashbangfr/coldcms/-/releases (or git clone the project, as you want)

Then you’ll need to launch the wsgi application located here: https://gitlab.com/hashbangfr/coldcms/-/blob/master/coldcms/wsgi.py

You can do this using several projects:

• uwsgi (our preferred approach)

• mod_wsgi (apache)

• CherryPy

• and so on..

You’ll have to pass some environment variables to the wsgi process (uwsgi for example), for the application to work as expected:

• DB_URL=postgres://coldcms:coldcms@db_host:5432/coldcms # adapt this for your setup, if you choose to use SQLite you can omit it

• BUILD_DIR=/srv/build # the directory under which the generated website will go, this directory will be served by your webserver (ex: nginx)

• STATIC_ROOT=/srv/build/static/ # Django STATIC_ROOT this directory needs to be served by your file server (ex: nginx) as well

• SECRET_KEY=CHANGE_ME # Django SECRET_KEY it should be a private, 40-character long randomly-generated string

• ALLOWED_HOSTS=localhost,127.0.0.1,your-domain.tld, the coma-separated list of hosts allowed to serve your application, corresponds to the Django ALLOWED_HOSTS

Here is a working example using uwsgi, with the application located under /srv/app and using SQLite:

[uwsgi]
socket = 0.0.0.0:8000
chdir = /srv/app/
module = coldcms.wsgi:application
master = true
processes = 4
threads = 2
uid = coldcms
gid = coldcms
buffer-size = 65535
env = BUILD_DIR=/srv/build
env = STATIC_ROOT=/srv/build/static/
env = SECRET_KEY=something_big_and_random

3. Setup Nginx to work with the backend

Nginx acts like a file server which serves the static website generated by the backend. You can choose any kind of file server as long as it can :

• serve files efficiently (HTML / images / assets …)

• proxy requests to /admin to the actual ColdCMS backend (set up on the 2nd step)

An example of a functional nginx config is available here: https://gitlab.com/hashbangfr/coldcms/-/blob/manual-install-doc/docker/nginx/nginx.conf

4 locations need to be served:

• /admin -> proxy to the python ColdCMS backend (step 2)

• / -> serve the HTML files generated by the backend (see BUILD_DIR in step 2)

• /media -> serve the medias files uploaded by the admin (it corresponds to $BUILD_DIR/media)

• /static -> serve the static files (see STATIC_ROOT in step 2)

Feel free to adapt it for your needs

You are a developer and you want to quickly have a look

Note: this has only been tested on Linux environments.

Install ColdCMS with pypi:

pip install coldcms

Run the quick launch command:

python -m coldcms

Before this command you can set the following environment variables :

• RUN_DJANGO_MIGRATION=0: do not run the migrations

• SETUP_INITIAL_DATA=0: do not setup the initial data, in case you want to keep the data you already have in your coldcms database

• COLLECT_STATIC=0: do not collect the static files. Don’t set that variable to 0 if it is your first time launching ColdCMS.

• CREATE_SUPERUSER=0: do not create a new superuser (you can have several superuser at a time, but not with the same username or email)

• BUILD_ASSETS=0: do not build build assets. Don’t set that variable to 0 if it is your first time launching ColdCMS.

• BUILD_STATIC=0: do not build static files. Don’t set that variable to 0 if you’ve also set SETUP_INITIAL_DATA to 0.

Example: CREATE_SUPERUSER=0 python -m coldcms will run the migrations, setup some new initial data, but will not create a new superuser.

You are a developer and you want to contribute to ColdCMS

Clone the gitlab repository, and read the Dev section below to install the ColdCMS development environment.

Follow the contribution guidelines.

Dev

Note: this has only been tested on Linux environments.

1. Install the dependencies

Install libjpeg and zlib, needed to work with images through the Pillow library. If you have a debian-based distribution, use the following commands:

sudo apt-get install zlib1g-dev
sudo apt-get install libjpeg-dev

Also, please install PurgeCSS and clean-css, to reduce the size of CSS files:

npm install -g purgecss@2.1.0 clean-css-cli@4.3.0

And to continue with javascript, please install static dependencies :

(cd coldcms/static/ && npm i --save-dev)

We use sass to transpile sass files to CSS. Make sure that the binary sass from the sassc package is present in your $PATH. In debian-based distributions, run the following:

sudo apt-get install sassc
sudo ln -s /usr/bin/sassc /usr/bin/sass # might be necessary if /usr/bin/sass doesn't exist after the previous command

Finally, run:

pip install -r requirements_dev.txt

2. Create a database

By default, ./manage.py migrate will create a sqlite3 database named coldcms.

• If you want to use a different database engine, you can specify it in the environment variable DB_URL. Make sure you have the proper database driver for the engine you want to use.

• If you want to use a different name for your sqlite database, you can specify it in the environment variable DB_NAME (useless for some engines as it is directly specified in the url - see table below).

As advised in the django documentation, if you’re new to databases, or you’re just interested in trying ColdCMS, use the default sqlite3 database, it is included in Python, so you won’t need to install anything else to support your database. When starting your first real project, however, you may want to use a more scalable database like PostgreSQL, to avoid database-switching headaches down the road.

Engine	DB_URL
PostgreSQL	postgres://USER:PASSWORD@HOST:PORT/NAME
PostGIS	postgis://USER:PASSWORD@HOST:PORT/NAME
MSSQL	mssql://USER:PASSWORD@HOST:PORT/NAME
MySQL	mysql://USER:PASSWORD@HOST:PORT/NAME
MySQL (GIS)	mysqlgis://USER:PASSWORD@HOST:PORT/NAME
SQLite	sqlite:///PATH
SpatiaLite	spatialite:///PATH
Oracle	oracle://USER:PASSWORD@HOST:PORT/NAME
Oracle (GIS)	oraclegis://USER:PASSWORD@HOST:PORT/NAME
Redshift	redshift://USER:PASSWORD@HOST:PORT/NAME

Replace PATH, USER, PASSWORD, HOST, PORT and NAME with the correct values.

Source

For example, if you want to use PostgreSQL :

systemctl status postgresql # make sure postgresql is running
createdb coldcms # create the coldcms postgres database
sudo -u postgres psql
CREATE USER username PASSWORD 'password';
ALTER ROLE username WITH SUPERUSER;
\q
export DB_URL="postgres://username:password@localhost:5432/coldcms"

3. Launch the development server

./manage.py migrate
./manage.py collectstatic
./manage.py compilemessages
./manage.py createsuperuser
./manage.py setup_initial_data # optional - loads data of a basic home page
./manage.py runserver

If collectstatic doesn’t work, try :

cd coldcms/static && npm i
cd ../.. && ./manage.py assets build

Custom theme for ColdCMS?

You can override coldcms style with your own theme.

You can create a Theme with the following command :

./manage.py collecttheme <theme>

That will create a directory theme at coldcms root. You can also create this directory everywhere you want. This directory must have the following structure

<theme>
├── static
│   ├── scss
│   │   └── <theme>.scss
|   |   └── theme_variables.scss
│   └── svg
└── templates

You have to set theme name and theme directory as environment variables

• THEME for theme name

• THEME_DIR for path to theme directory

There is also an option to customize the theme path :

./manage.py collecttheme <theme> --directory=<path>

To override a specific template, in the templates directory of your theme, add the directory

To override a specific template file, in the “templates” folder of your theme, you need to add a folder named like the original folder containing the template file. Then you must create the template file with the same name as well.

Example :

Original struct :

generic_page <app>
└── templates
    └── generic_page
        └── generic_page.html

In your theme :

<theme>
└── templates
    └── generic_page
        └── generic_page.html

Finally, for the surcharge to be properly applied, you will need to define the name and path of your theme. In the settings/base.py file there are the global variables “THEME” and “THEME_DIR” provided for this purpose. If you do not want to modify the settings.py file, you can define these variables with the terminal :

export THEME=<theme>
export THEME_DIR=<path theme>