Alaveteli

EN

Installing Alaveteli using Docker

Docker provides an easy method to set up virtual development environments. We bundle an example docker-compose.yml in the repository, which builds and runs a Docker container for you.

Although this is just one of several ways to install Alaveteli, it’s the best and easiest way to install it for development.

Remember that you must customise Alaveteli before it’s ready for the public to use, so installing a development site is a necessary part of installing Alaveteli.

The included steps will use Docker to create a development environment where you can run the test suite and the development server, make changes to the codebase and — significantly for customising Alaveteli — create your own theme.

What’s Docker? Docker is a tool that lets you run applications in self-contained isolated envrionments called a container. When you use Docker to install Alaveteli, it creates a container that has all the dependencies Alaveteli needs.

Because everything is in the container, it doesn’t need to find or change anything on your own machine. This means you can work on any operating system that runs Docker, instead of needing to match what Alaveteli expects.

You can edit the files just like any other files on your machine (because the folder is "shared" between your machine and the container), and the container uses port-forwarding so you can access its Alaveteli server through your browser.

See the Docker documentation for more information.

How to set up the Docker container

The supplied scripts in the ./docker directory will create you a Docker container which has everything you need to work on Alaveteli.

To create a Docker container with Alaveteli installed, run the setup script:

    ./docker/setup

This will build the required Docker images, download the default Alaveteli theme, install all dependencies, create and populate the database with sample data and create an initial search index

How to start Alaveteli server

To start Alaveteli, run the rails server:

    ./docker/server

You can now visit the application in your browser (on the same machine that is running Docker) at http://0.0.0.0:3000.

How to run commands

While working with Alaveteli you might need to run commands within the Docker container.

Depending on the version of Docker installed you might need to substitute docker compose for docker-compose in the commands below.

The Rails console can be launch by running:

    docker compose run --rm app bin/rails console

Run other Rails commands:

    docker compose run --rm app bin/rails routes
    docker compose run --rm app bin/rails runner "puts 1"
    # etc…

Run a command with an environment variable set:

    docker compose run -e RAILS_ENV=test --rm app bin/rails db:migrate

Use -T to pipe local files to scripts run in the app container.

    cat spec/fixtures/files/incoming-request-plain.email |
      docker compose run --rm -T app script/mailin

How to stop the server

You don’t need to stop Alaveteli right away, but when you do this can be done by pressing Ctrl-C to interrupt the ./docker/server script.

How to reset the container

While working on Alaveteli you may find you might need to reset the container back to its initial state. This can be done by running:

    ./docker/reset

How to view local emails

The Docker installation comes with a MailHog instance, you can visit this at http://0.0.0.0:1080.

What next?

The Docker installation you’ve just done has loaded test data, which includes an administrator account (Joe Admin). If you just want to dive straight into customisation, every new Alaveteli site needs its own theme.