<commit_before>.. _install-dev:

Installation guide (development)
================================

Installing System Packages
--------------------------

Web assets such as JavaScript and SCSS files are compiled using `Webpack <https://webpack.js.org>`_, which
requires NodeJS to be present. You can find information on how to install NodeJS
`here <https://nodejs.org/en/download/package-manager/>`_.

Do not use the default NodeJS packages from your Linux distribution as they are usually outdated or come wit
an outdated npm version.

CentOS/Fedora
+++++++++++++

.. code-block:: shell

    yum install -y gcc redis python-devel python-virtualenv libjpeg-turbo-devel libxslt-devel libxml2-devel \
        libffi-devel pcre-devel libyaml-devel redhat-rpm-config \
        postgresql postgresql-server postgresql-contrib libpq-devel
    systemctl start redis.service postgresql.service


Debian/Ubuntu
+++++++++++++

.. code-block:: shell

    apt install -y --install-recommends python-dev python-virtualenv libxslt1-dev libxml2-dev libffi-dev libpcre3-dev \
        libyaml-dev build-essential redis-server postgresql libpq-dev

Then on Debian::

    apt install -y libjpeg62-turbo-dev

And on Ubuntu::

    apt install -y libjpeg-turbo8-dev zlib1g-dev


macOS
+++++

We recommend that you use `Homebrew <https://brew.sh/>`_::

    brew install python2 redis libjpeg libffi pcre libyaml postgresql
    brew services start postgresql
    pip install virtualenv

Note: Homebrew dropped support for the python2 formula at the end of 2019.
As an alternative you can install it directly using the latest commit::

    brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/86a44a0a552c673a05f11018459c9f5faae3becc/Formula/python@2.rb


Creating the directory structure
--------------------------------

You will need a directory in your file system to store Indico as well as its data files (archives, etc...). Some
developers keep all their code inside a ``dev`` or ``code`` dir. We will assume ``dev`` here.

.. code-block:: shell

    mkdir -p ~/dev/indico/data

We will need a virtualenv where to run Indico::

    cd ~/dev/indico
    virtualenv env -p /usr/bin/python2.7


Cloning Indico
--------------

First, let's clone Indico's code base. If you're going to contribute back to the project, it's probably best if you
clone your own `GitHub fork of the project <https://help.github.com/articles/fork-a-repo/>`_ and set it as the origin::

    git clone <EMAIL>:<your-github-username>/indico.git src
    cd src
    git remote add upstream https://github.com/indico/indico.git
    cd ..

Otherwise, cloning the upstream repository as the origin should be enough::

    git clone https://github.com/indico/indico.git src

If you're going to be changing the standard Indico plugins and/or the documentation, you can also clone those::

    mkdir plugins
    git clone https://github.com/indico/indico-plugins.git plugins/base
    git clone https://github.com/indico/indico-user-docs.git user-docs


Setting up Maildump (recommended)
---------------------------------

Some actions in Indico trigger automatic e-mails. Those will normally have to be routed through an SMTP server.
This can become a problem if you're using production data and/or real e-mails, as users may end up being spammed
unnecessarily. This is why we advise that you include a fake SMTP server in your development setup.
`Maildump <https://github.com/ThiefMaster/maildump>`_ does exactly this and runs on Python. It should be quite simple
to set up::

    virtualenv maildump -p /usr/bin/python2.7
    ./maildump/bin/pip install -U pip setuptools
    ./maildump/bin/pip install maildump
    ./maildump/bin/maildump -p /tmp/maildump.pid

You'll then be able to access the message log at `<http://localhost:1080>`_.


Creating the DB
---------------

.. code-block:: shell

    sudo -u postgres createuser $USER --createdb
    sudo -u postgres createdb indico_template -O $USER
    sudo -u postgres psql indico_template -c "CREATE EXTENSION unaccent; CREATE EXTENSION pg_trgm;"
    createdb indico -T indico_template


Configuring
-----------

Let's get into the Indico virtualenv::

    source ./env/bin/activate
    pip install -U pip setuptools

    cd src
    pip install -r requirements.dev.txt
    pip install -e .
    npm ci

Then, follow the instructions given by the wizard::

    indico setup wizard --dev

You can then initialize the DB::

    indico db prepare

.. _run-dev:

Running Indico
--------------

You will need two shells running in parallel. The first one will run the webpack watcher, which compiles
the JavaScript and style assets every time you change them:<commit_msg>Add commands for building locales<commit_after>.. _install-dev:

Installation guide (development)
================================

Installing System Packages
--------------------------

Web assets such as JavaScript and SCSS files are compiled using `Webpack <https://webpack.js.org>`_, which
requires NodeJS to be present. You can find information on how to install NodeJS
`here <https://nodejs.org/en/download/package-manager/>`_.

Do not use the default NodeJS packages from your Linux distribution as they are usually outdated or come wit
an outdated npm version.

CentOS/Fedora
+++++++++++++

.. code-block:: shell

    yum install -y gcc redis python-devel python-virtualenv libjpeg-turbo-devel libxslt-devel libxml2-devel \
        libffi-devel pcre-devel libyaml-devel redhat-rpm-config \
        postgresql postgresql-server postgresql-contrib libpq-devel
    systemctl start redis.service postgresql.service


Debian/Ubuntu
+++++++++++++

.. code-block:: shell

    apt install -y --install-recommends python-dev python-virtualenv libxslt1-dev libxml2-dev libffi-dev libpcre3-dev \
        libyaml-dev build-essential redis-server postgresql libpq-dev

Then on Debian::

    apt install -y libjpeg62-turbo-dev

And on Ubuntu::

    apt install -y libjpeg-turbo8-dev zlib1g-dev


macOS
+++++

We recommend that you use `Homebrew <https://brew.sh/>`_::

    brew install python2 redis libjpeg libffi pcre libyaml postgresql
    brew services start postgresql
    pip install virtualenv

Note: Homebrew dropped support for the python2 formula at the end of 2019.
As an alternative you can install it directly using the latest commit::

    brew install https://raw.githubusercontent.com/Homebrew/homebrew-core/86a44a0a552c673a05f11018459c9f5faae3becc/Formula/python@2.rb


Creating the directory structure
--------------------------------

You will need a directory in your file system to store Indico as well as its data files (archives, etc...). Some
developers keep all their code inside a ``dev`` or ``code`` dir. We will assume ``dev`` here.

.. code-block:: shell

    mkdir -p ~/dev/indico/data

We will need a virtualenv where to run Indico::

    cd ~/dev/indico
    virtualenv env -p /usr/bin/python2.7


Cloning Indico
--------------

First, let's clone Indico's code base. If you're going to contribute back to the project, it's probably best if you
clone your own `GitHub fork of the project <https://help.github.com/articles/fork-a-repo/>`_ and set it as the origin::

    git clone git@github.com:<your-github-username>/indico.git src
    cd src
    git remote add upstream https://github.com/indico/indico.git
    cd ..

Otherwise, cloning the upstream repository as the origin should be enough::

    git clone https://github.com/indico/indico.git src

If you're going to be changing the standard Indico plugins and/or the documentation, you can also clone those::

    mkdir plugins
    git clone https://github.com/indico/indico-plugins.git plugins/base
    git clone https://github.com/indico/indico-user-docs.git user-docs


Setting up Maildump (recommended)
---------------------------------

Some actions in Indico trigger automatic e-mails. Those will normally have to be routed through an SMTP server.
This can become a problem if you're using production data and/or real e-mails, as users may end up being spammed
unnecessarily. This is why we advise that you include a fake SMTP server in your development setup.
`Maildump <https://github.com/ThiefMaster/maildump>`_ does exactly this and runs on Python. It should be quite simple
to set up::

    virtualenv maildump -p /usr/bin/python2.7
    ./maildump/bin/pip install -U pip setuptools
    ./maildump/bin/pip install maildump
    ./maildump/bin/maildump -p /tmp/maildump.pid

You'll then be able to access the message log at `<http://localhost:1080>`_.


Creating the DB
---------------

.. code-block:: shell

    sudo -u postgres createuser $USER --createdb
    sudo -u postgres createdb indico_template -O $USER
    sudo -u postgres psql indico_template -c "CREATE EXTENSION unaccent; CREATE EXTENSION pg_trgm;"
    createdb indico -T indico_template


Configuring
-----------

Let's get into the Indico virtualenv::

    source ./env/bin/activate
    pip install -U pip setuptools

    cd src
    pip install -r requirements.dev.txt
    pip install -e .
    npm ci

Then, follow the instructions given by the wizard::

    indico setup wizard --dev

You can then initialize the DB::

    indico db prepare

To build the locales, use:

.. code-block:: shell

    indico i18n compile-catalog
    indico i18n compile-catalog-react

.. _run-dev:

Running Indico
--------------

You will need two shells running in parallel. The first one will run the webpack watcher, which compiles
the JavaScript and style assets every time you change them:
{'fraction_non_alphanumeric': 0.1158658395542004, 'fraction_numerical': 0.010303858689937967, 'mean_word_length': 3.101768003449763, 'pattern_counts': {'":': 0, '<': 18, '<?xml version=': 0, '>': 18, 'https://': 20, 'lorem ipsum': 0, 'www.': 0, 'xml': 4}, 'pii_count': 3, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '962925', 'n_tokens_mistral': 2939, 'n_tokens_neox': 2689, 'n_words': 1090}