Commit ac2cc6b3 authored by Mayel's avatar Mayel

Merge branch 'chore/readme-developers' into 'develop'

Move development setup instructions into

See merge request !15
parents 13c3ee23 819d7eb2
Pipeline #64956289 passed with stages
in 9 minutes and 8 seconds
# Installation and deployment
These instructions are for installing MoodleNet in production. If you
wish to run MoodleNet in development, please refer to our [Developer
### Configuring the back-end
In the `config/` directory, there are following default config files:
* `config.exs`: default base configuration
* `dev.exs`: default extra configuration for `MIX_ENV=dev`
* `prod.exs`: default extra configuration for `MIX_ENV=prod`
Do NOT modify the files above. Instead, overload any settings from the above files by editing the following files:
* `dev.secret.exs`: custom extra configuration for `MIX_ENV=dev`
* `prod.secret.exs`: custom extra configuration for `MIX_ENV=prod`
### Install using Docker containers (recommended)
1. Make sure you have [Docker](, a recent [docker-compose]( (which supports v3 configs), and [make]( installed:
$ docker version
Docker version 18.09.1-ce
$ docker-compose -v ±[●][develop]
docker-compose version 1.23.2
$ make --version
GNU Make 4.2.1
2. Clone this repository and change into the directory:
$ git clone
$ cd federated
3. Build the docker image:
$ make build
(During subsequent builds, you may want to build using the docker cache: `make build_with_cache`)
4. Start the docker containers with docker-compose:
$ docker-compose up
5. The backend should now be running at [http://localhost:4000/](http://localhost:4000/).
6. If that worked, start the app as a daemon next time:
$ docker-compose up -d
#### Configuration
The docker image can be found in:
The docker image needs the environment variables to work, a list of which can be found in the file `config/docker.env` in this same repository.
The easiest way to launch the docker image is using the `docker-compose` tool.
The `docker-compose.yml` uses `config/docker.env` to launch a `moodlenet` container and all its dependencies, currently that means an extra postgres container.
#### Docker commands
The first time you launch the docker instance the database is not created.
There are several commands to make the first launch easier.
We will use `docker-compose` to show the commands:
* `docker-compose run --rm web bin/moodle_net create_db` creates the database
* `docker-compose run --rm web bin/moodle_net migrate_db` creates the database and runs the migrations
* `docker-compose run --rm web bin/moodle_net drop_db` drops the database
Other important commands are:
* `docker-compose up` launches the service, by default at the port 4000.
* `docker-compose run --rm web /bin/sh` runs a simple shell inside of the container, useful to explore the image
* `docker-compose run --rm web bin/moodle_net console` runs an `iex` console
* `docker-compose exec web bin/moodle_net remote_console` runs an `iex` console when the service is already running.
* `docker-compose run --rm web bin/moodle_net help` returns all the possible commands
There is a command that currently is not working: `seed_db`.
The reason is that to generate ActivityPub IDs we need the URL where the server is running, but `Phoenix` is not launched in this command.
However, we can do so by running the following command in an `iex` console:
`iex> MoodleNet.ReleaseTasks.seed_db([])`
#### Building a Docker image
There is a `Makefile` with two commands:
* `make build` which builds the docker image in `moodlenet:latest` and `moodlenet:$VERSION-$BUILD`
* `make run` which can be used to run the docker built docker image without `docker-compose`
### DevOps information
The [Dockerfile]( uses the [multistage build]( feature to make the image as small as possible.
It is a very common release using [Distillery](
It generates the release which is later copied into the final image:
* [/Dockerfile#L57](
* [/Dockerfile#L80](
### Alternative installation without Docker
#### 1. Install dependencies
* Postgres version 9.6 or newer
* Build tools
* Elixir version 1.7.4 with OTP 21 (or possibly newer). If your distribution only has an old version available, check [Elixir's install page]( or use a tool like [asdf]( (run `asdf install` in this directory).
#### 2. Install the app
* Clone this repo.
* Run `mix deps.get` to install elixir dependencies.
* Run `mix generate_config`. This will ask you a few questions about your instance and generate a configuration file in `config/generated_config.exs`. Check that and copy it to either `config/dev.secret.exs` or `config/prod.secret.exs`. It will also create a `config/setup_db.psql`; you may want to double-check this file in case you wanted a different username, or database name than the default. Then you need to run the script as PostgreSQL superuser (i.e. `sudo su postgres -c "psql -f config/setup_db.psql"`). It will create a db user, database and will setup needed extensions that need to be set up. Postgresql super-user privileges are only needed for this step.
* For these next steps, the default will be to run the server using the dev configuration file, `config/dev.secret.exs`. To run them using the prod config file, prefix each command at the shell with `MIX_ENV=prod`. For example: `MIX_ENV=prod mix phx.server`.
* Run `mix ecto.migrate` to run the database migrations. You will have to do this again after certain updates.
* You can check if your instance is configured correctly by running it with `mix phx.server` and checking the instance info endpoint at `/api/v1/instance`. If it shows your uri, name and email correctly, you are configured correctly. If it shows something like `localhost:4000`, your configuration is probably wrong, unless you are running a local development setup.
* The common and convenient way for adding HTTPS is by using Nginx as a reverse proxy. You can look at example Nginx configuration in `installation/moodle_net.nginx`. If you need TLS/SSL certificates for HTTPS, you can look get some for free with letsencrypt:
The simplest way to obtain and install a certificate is to use [Certbot.]( Depending on your specific setup, certbot may be able to get a certificate and configure your web server automatically.
## Running
By default, the back-end listens on port 4000 (TCP), so you can access it on http://localhost:4000/ (if you are on the same machine). In case of an error it will restart automatically.
The MoodleNet frontend is a seperate app:
\ No newline at end of file
# MoodleNet Developer FAQ
Hello, potential contributor!
This is a work in progress guide to getting MoodleNet up and running
as a developer. Please ask questions in the [public Telegram chat]( or
via GitLab if something is not clear.
Happy hacking!
## Getting set up
There are three options. The easy option should work the best for most
### Easy Option - fully managed via docker-compose
1. Dependencies:
* `make`
* Docker
* Docker Compose (recent version)
2. From a fresh checkout, download the dependencies and setup the database:
make dev-setup
3. You should then be able to run with:
make dev
#### Other useful makefile tasks
- `make dev-build` - rebuild the dev docker image
- `make dev-db` - rebuild the development database
- `make dev-test-db` - rebuild the test database
- `make dev-test` - run the tests
- `make dev-db-up` - launch only the database
#### Forwarded ports
* `4000` - moodlenet http listener
* `5432` - postgres database server
### Semi-Manual Option - docker-managed dataabase
* A recent elixir version (1.8.0+)
MoodleNet takes some configuration in the form of environment
variables so we don't need to rebuild the docker images to change the
configuration. The first task therefore is to export the development
environment in the current shell:
eval "$(make dev-exports)"
You can then install the elixir deps:
mix deps.get
Launch the database (in a second shell, preferably):
make dev-db-up
And reset it:
mix ecto.reset
Finally, you may launch the application in iex:
iex -S mix phx.server
### Fully Manual
If you wish to avoid docker entirely, you will need to follow the
steps above, except:
1. After setting the environment with `eval $(make dev-exports)`, you
will need to export the following variables in the environment to
match the configuration of your database:
2. You will not need to run `make dev-db-up`
## Documentation
The code is somewhat documented inline. You can read the resulting [Module & Function Documentation]( on the project website.
If you add more documentation (thanks!), you can generate HTML docs (using `Exdoc`) by running `mix docs`.
## Internationalisation
The backend code currently has very few translatable strings, basically error messages transactional emails:
* Email subject lines in `MoodleNet.Email` (eg: [moodle_net/email.ex#L8](
* Email templates in [moodle_net_web/email/](
* Errors passed through Gettext in `MoodleNetWeb.ErrorHelpers` and `MoodleNetWeb.GraphQL.Errors`
The locale is set using the `MoodleNetWeb.Plugs.SetLocale` plug which checks the header or a param.
If you've added any localisable fields, you should run `mix gettext.extract` to extract them into `/priv/gettext/en/LC_MESSAGES/`. Upload those files to the translation system (eg. Transifex).
If you've downloaded or received new translated files, copy them to the approriate languages folder(s) in `/priv/gettext/` before rebuilding the app.
## What happens when I get this error?
### (Mix) Package fetch failed
** (Mix) Package fetch failed and no cached copy available (
In this case, distillery made a new release and retired the old
release from hex. The new version (`2.0.14`) is quite close to the
version we were depending on (`2.0.12`), so we chose to upgrade:
mix deps.update distillery
This respects the version bounds in `mix.exs` (`~> 2.0`).
### `(DBConnection.ConnectionError) tcp recv: closed`
** (DBConnection.ConnectionError) tcp recv: closed (the connection was closed by the pool, poissibly due to a timeout or because the pool has been terminated)
In this case, the seeds were unable to complete because a query took
too long to execute on your machine. You can configure the timeout to
be larger in the `dev` environment:
1. Open `config/dev.exs` in your editor.
2. Find the database configuration (search for `MoodleNet.Repo`).
3. Add `timeout: 60_000` to the list of options.
The finished result should look like this (did you remember to add a
comma at the end of the `pool_size` line?):
config :moodle_net, MoodleNet.Repo,
adapter: Ecto.Adapters.Postgres,
username: "postgres",
password: "postgres",
database: "moodle_net_dev",
hostname: System.get_env("DATABASE_HOST") || "localhost",
pool_size: 10,
timeout: 60_000
## Running
By default, the back-end listens on port 4000 (TCP), so you can access it on http://localhost:4000/
The MoodleNet frontend is a seperate app:
This diff is collapsed.
......@@ -18,7 +18,7 @@ defmodule MoodleNet.Mixfile do
docs: [
main: "readme", # The first page to display from the docs
logo: "assets/static/images/moodlenet-logo.png",
extras: [""] # extra pages to include
extras: ["", "", ""] # extra pages to include
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment