View Source Hosting guide

Install using Co-op Cloud (recommended) which is an alternative to corporate cloud services built by tech co-ops, and provides handy tools for setting up and managing many self-hosted free software tools using ready-to-use "recipes". Very useful if you'd like to host Bonfire alongside other open and/or federated projects.

1. Install Abra on your machine
2. Set up a server with co-op cloud
3. Use the Bonfire recipe and follow the instructions there, including editing the config in the env file at ~/.abra/servers/your_server/your_app.env (see prepare the config for details about what to edit)
4. Run the abra deploy command and done!

1. Install dependencies.

The easiest way to manage the docker image is using just commands.

The docker-compose.release.yml uses config/prod/.env to launch a container with the necessary environment variables along with its dependencies, currently that means an extra postgres container, along with a reverse proxy (Caddy server, which you may want to replace with nginx or whatever you prefer).

Make sure you have Docker, with the compose plugin, and just installed:

$ docker version
Docker Engine - Community - 23.0.1

$ docker compose version
Docker Compose version v2.16.0

$ just --version
just 1.13.0
...
copy

2. Clone this repository and change into the directory:

git clone --depth 1 https://github.com/bonfire-networks/bonfire-app.git bonfire && cd bonfire
copy

3. Specify what flavour you want to run in production:

The first thing to do is choose what flavour of Bonfire (eg. ember, social, community, or cooperation) you want to deploy, as each flavour uses different Docker images and set of configs. For example if you want to run the social flavour:

• export MIX_ENV=prod FLAVOUR=social WITH_DOCKER=yes

You may also want to put this in the appropriate place in your system so your choice of flavour is remembered for next time (eg. ~/.bashrc or ~/.zshrc)

4. Run just config to initialise some default config and then edit the config in the ./.env file (see prepare the config for details about what to edit).

Now that your tooling is set up, you have the choice of using pre-built images or building your own. For example if your flavour does not have a prebuilt image on Docker Hub, or if you want to customise any of the extensions, you can build one yourself.

Using pre-built Docker images (easy mode)

• The image entry in docker-compose.release.yml will by default use the image on Docker Hub which corresponds to your chosen flavour (see step 1 above for choosing your flavour).

You can see the images available per flavour, version (we currently recommend using the latest tag), and architecture at https://hub.docker.com/r/bonfirenetworks/bonfire/tags

5. Try running the app!

Custom Docker build

Building your own Docker image is useful if you want to make code changes or add your own extensions.

Dockerfile.release uses the multistage build feature to just the image as small as possible. It generates the OTP release which is later copied into the final image packaged in an Alpine linux container.

There is a justfile with relevant commands (make sure set the MIX_ENV=prod env variable):

• just rel-build-locked which builds the docker image of the latest release
• just rel-build which builds the docker image, including local changes to any cloned extensions in ./extensions/
• just rel-tag adds the "latest" tag to your last build, so that it will be used when running

Once you've built and tagged your image, you may need to update the image name in docker-compose.release.release.yml to match (either your local image name if running on the same machine you used for the build, or a remote image on Docker Hub if you pushed it) and then follow the same steps as for option A1.

For production, we recommend to set up a CI workflow to automate this, for an example you can look at the one we currently use.

Finally, try running the app!

Running with Docker

1. Before running the app for the first time, but after having prepared the config, you should run just setup-prod which will get the instance ready.

2. The you can start the docker containers with docker-compose: just rel-run

You can run this at the prompt bin/bonfire remote to enter Elixir's iex environment. Once there in case migrations have not run automatically you can run Bonfire.Common.Repo.migrate to initialise your database.

3. The backend should now be running at http://localhost:4000/. Yay, you're up and running!

4. If that worked, start the app as a daemon to it stays running in the background: just rel-run-bg

Alternatively, just rel-run-bg db if you want to run the backend + db but not the web proxy, or just rel-run-bg db search if you want to run the full-text search index.

Running a custom build without Docker.

1. Install dependencies.

• Postgres (or Postgis) version 12 or newer
• just
• Elixir version 1.15+ with OTP 25+ (see the .tool-versions to double check the versions we're currently using). If your distribution only has an old version available, check Elixir's install page or use a tool like mise (run mise install in this directory) or asdf. Note: Source versions of Elixir >=1.17 and <1.17.3 have bugs that can freeze compilation when using the Pathex library, which bonfire does, so please use 1.16 or 1.17.3+ (or you can set WITH_PATHEX=0 in env to disabled the use of that library).

2. Clone this repository and change into the directory:

git clone --depth 1 https://github.com/bonfire-networks/bonfire-app.git bonfire && cd bonfire
copy

3. Specify what flavour you want to run in production:

The first thing to do is choose what flavour of Bonfire (eg. ember, social, community, or cooperation) you want to deploy, as each flavour uses different Docker images and set of configs. For example if you want to run the social flavour:

• export FLAVOUR=social MIX_ENV=prod WITH_DOCKER=no

You may also want to put this in the appropriate place in your system so your choice of flavour is remembered for next time (eg. ~/.bashrc or ~/.zshrc)

4. Run just config to initialise some default config and then edit the config in the ./.env file (see prepare the config for details about what to edit).

5. Run just setup-prod

6. Run just rel-build to create an elixir release. This will create an executable in your _build/prod/rel/bonfire directory. Note that you will need just to pass in the .env file to the executable, like so: just cmd _build/prod/rel/bonfire/bin/bonfire <bonfire command>. Alternatively, this file can be sourced by source .env instead. We will be using the bin/bonfire executable as called from just from here on.

7. Running the release

• Create a database, and a user, fill out the .env with your credentials and secrets

• You will need to use just in order to pass the .env file to the executable. This can be accomplished by running just cmd _build/prod/rel/bonfire/bin/bonfire <bonfire command>. Just works from the root directory of the justfile, not your current directory.

• If you’re using RDS or some other locked down DB, you may need to run CREATE EXTENSION IF NOT EXISTS citext WITH SCHEMA public; on your database with elevated privileges.

• You may also need to enable the postgis extension manually by running CREATE EXTENSION IF NOT EXISTS postgis WITH SCHEMA public; on your database with elevated privileges.

• You can check if your instance is configured correctly and get to the iex console by running bin/bonfire start

• The migrations should automatically run on first boot, but if you run into troubles the migration command is: Bonfire.Common.Repo.migrate() in the iex console.

• To run the instance as a daemon, use bin/bonfire start daemon. Yay, you're up and running!

8. Adding HTTPS

The common and convenient way for adding HTTPS is by using a reverse proxy like Nginx or Caddyserver (the latter of which is bundled as part of the docker compose setup).

Some web servers (like Caddy or Traefik) can handle generating and setting up HTTPS certificates automatically, but if you need TLS/SSL certificates for nginx, 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.

There is an example nginx configuration provided at config/deploy/nginx.conf and one for Caddy at config/deploy/Caddyfile2-https

NOTE: If you've built from source, you should point the web server root directory to be _build/prod/rel/bonfire/lib/bonfire-[current-version]/priv/static

This repo contains an experimental Flake and Nix module. These are not ready for production.

Here are the detailed steps to deploy it:

• run a recent version of Nix or NixOS: https://nixos.wiki
• enable Flakes: https://nixos.wiki/wiki/Flakes#Installing_flakes
• add sandbox = false in your nix.conf
• fetch and build the app and dependencies: nix run github:bonfire-networks/bonfire-app start_iex
• add it as an input to your system flake.
• add an overlay to just the package available
• add the required configuration in your system

Your flake.nix file would look like the following. Remember to replace myHostName with your actual hostname or however your deployed system is called.

{
  inputs.bonfire.url = "github:bonfire-networks/bonfire-app/main";
  outputs = { self, nixpkgs, bonfire }: {
    overlay = final: prev: with final;{
      # a package named bonfire already exists on nixpkgs so we put it under a different name
      elixirBonfire = bonfire.packages.x86_64-linux.default;
    };
    nixosConfigurations.myHostName = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        {
          environment.systemPackages = [ agenix.defaultPackage.x86_64-linux ];
          nixpkgs.overlays = [ self.overlay ];
        }
        ./myHostName.nix
        bonfire.nixosModules.bonfire
      ];
    };
  };
}copy

Then your myHostName.nix would look like the following:

{ config, lib, pkgs, ... }:

{
  services.bonfire = {
    # you will additionally need to expose bonfire with a reverse proxy, for example caddy
    port = 4000;
    package = pkgs.elixirBonfire;
    dbName = "bonfire";
    # the environment should contain a minimum of
    #   SECRET_KEY_BASE
    #   SIGNING_SALT
    #   ENCRYPTION_SALT
    #   RELEASE_COOKIE
    # have a look into nix/module.nix for more details
    # the way to deploy secrets is beyond this readme, but I would recommend agenix
    environmentFile = "/run/secrets/bonfireEnv";
    dbSocketDir = "/var/run/postgresql";
  };
	
	# this is specifically for a reverse proxy, which is primarily used for SSL certs
	services.ngnix = {
		enable = true;
		forceSSL = true;
		enableACME = true;
		virtualHosts."myHostName".locations.proxyPass = "http://localhost:4000";
	};
	
	# You will need to accept ACME's terms and conditions if you haven't elsewhere in your configuration
	security.acme.defaults.email = "you@myHostName.com";
	security.acme.acceptTerms = true;

  # this is uniquely for database backup purposes
  # replace myBackupUserName with the user name that will do the backups
  # if you want to do backups differently, feel free to remove this part of the config
  services.postgresql = {
    ensureDatabases = [ "bonfire" ];
    ensureUsers = [{
      name = "myBackupUserName";
      ensurePermissions = { "DATABASE bonfire" = "ALL PRIVILEGES"; };
    }];
  };
}copy