Installing From Source

These instructions assume a basic knowledge of Linux/Unix and command-line tools.

open890 is currently supported under Linux, or Unix-like operating systems like MacOS. You can also follow these instructions in Windows 10 if you have WSL installed - much of this project was written under WSL. If you are on Windows and do not have WSL installed, you can still compile the app. See Developing on Windows for more information.

You will need Elixir (and thus, Erlang) and NodeJS installed, particularly if you are either developing features for open890, or using a non-binary (e.g. source) release.

It is very important to have the versions of the tools specified in .tool-versions installed, and that the correct version is given to you when you run the command.

Using a tool like asdf is recommended to manage the various versions of the development dependencies.

Development Prerequsites

• Raspberry Pi users may need to install the following packages:

  sudo apt -y install autoconf libssl-dev libncurses5-dev zip unzip build-essential python2
  

• Fedora/Red Hat users will need to install the following packages:

  sudo yum install autoconf openssl-devel ncurses-devel
  

Clone the repository

    git clone https://github.com/tonyc/open890.git
    cd open890

Optional: Check out the develop branch

There are two main branches in the repository: main and develop

• main can be interpreted as "stable", but unreleased. Code that lands in main is next in line for a release. This is the default branch you get when cloning the repository.

• develop should be considered "unstable". Things may break, things may change around rapidly, etc.

To check out the develop branch:

    git checkout develop

Using asdf

asdf is a tool to manage installing specific versions of various programming languages and development tools. It is the recommended way to build open890 from source locally.

• Install asdf

• Install erlang, elixir and nodeJS plugins

  asdf plugin add erlang https://github.com/asdf-vm/asdf-erlang.git
  asdf plugin-add elixir https://github.com/asdf-vm/asdf-elixir.git
  asdf plugin-add nodejs https://github.com/asdf-vm/asdf-nodejs.git
  

• Add the NodeJS keyring:

   bash -c '${ASDF_DATA_DIR:=$HOME/.asdf}/plugins/nodejs/bin/import-release-team-keyring'  
  

• Install the specific versions listed in the .tool-versions file:

  asdf install
  

• The Erlang install will take a very long time on a Raspberry Pi. You may also see scary-looking messages during the Erlang install that says something like "fop is missing" or "documentation cannot be built" - this is OK.

• Once everything has installed, you should have the following versions installed (per .tool-versions):

  $ elixir --version
  Erlang/OTP 23 ....
  Elixir 1.11.3 ...
  
  $ node --version
  v14.15.4
  
  $ npm --version
  6.14.10
  

Please note that if you have incorrect versions installed, you may run into installation problems not covered by this guide. In particular, having the incorrect version of npm installed may affect the javascript/css dependencies and build process.

Compile the app

• Install dependencies with mix deps.get. First-time users may need to answer Y to a couple of prompts

• Compile with mix compile

• Once that's finished, compile assets:

  cd assets/
  npm install
  cd ..
  

Start your server:

• Run mix phx.server

Now you can visit http://localhost:4000 from your browser.

Stopping your server

Type ^C^C (aka: ctrl-c twice)