Welcome

Welcome to Nexpo - Next generation Expo!

This project aims to to supply ARKAD with an inhouse project management system.

Table of Contents

Expand

• System Requirements
• Technical Description
  • Mailing
  • Folder structure
• Development
  • Setup environment
  • Reset Linux environment
  • Implement things
    • Development lifecycle
    • Testing
      • Recap of TDD:
      • Writing tests for backend
  • Helpful things
    • Create a non-protected endpoint
    • Create a protected endpoint
  • Dev servers
  • Helpful scripts
  • Documentation
  • Setup your Editor
• Deployment
  • Heroku
• Who do I contact?

System Requirements

The system requires these programs to be installed. The project intends to always follow stable releases. The system is verified to work with the following setup

• Elixir 1.8.2 Installation instructions
• Erlang OTP 22.0.7 - Installed automatically with Elixir
• Node 11.9.0 Installation instructions
• PostgreSQL 10.10 Installation instruction

When updating system requirements, make sure you update accordingly the following locations

• Node
  • phoenix_static_buildpack.config
  • package.json
  • priv/react_app/package.json
  • .travis.yml
• Elixir
  • mix.exs
  • elixir_buildpack.config
  • .travis.yml

Technical Description

The backend is configured with Phoenix Framework. Phoenix Framework has a fantastic User Guide, there is a full Phoenix Project Example and there exists two nice issues for learning Issue 81 - Posts and Issue 82 - Post Comments.

Mailing

Mailing is configured with Bamboo.

Folder structure backend

The folder structure follows default Phoenix structure

Structure

.
|-- config/                           # Config for all environments
|   |-- config.exs                    # Shared config
|   |-- dev.exs                       # Config for development
|   |-- prod.exs                      # Config for production
|   |-- test.exs                      # Config for test
|
|-- docs/                             # Auto generated docs for HTTP API
|
|-- documentation/                    # Requirements specifications etc
|
|-- lib/
|   |-- nexpo/
|   |   |-- NAME.ex
|   |
|   |-- nexpo.ex
|
|-- priv/
|   |-- gettext/
|   |-- repo/                         # Database structure
|       |-- migrations                # Database migrations
|       |   |-- MIGRATION_NAME.exs    # Database migration
|       |
|       |-- seeds.exs                 # Seeds defining initial data
|
|-- test/                             # Tests
|   |-- acceptance/                   # Acceptance tests
|   |   |-- TEST_NAME.exs
|   |
|   |-- models/                       # Model tests
|   |   |-- TEST_NAME.exs
|   |
|   |-- support/                      # Support modules
|   |   |-- SUPPORT_NAME.exs
|   |
|   |-- views/                        # Views
|   |   |-- TEST_NAME.exs
|   |
|   |-- test_helper.exs               # Helper for tests
|
|-- web/                              # Defines business logic
|   |-- channels/                     # Websockets
|   |   |-- NAME.ex
|   |
|   |-- controllers/                  # Controllers
|   |   |-- NAME.ex
|   |
|   |-- mailers/                      # Email stuff
|   |   |-- mailer.ex                 # Responsible for sending emails
|   |   |-- NAME.ex                   # Defines emails
|   |
|   |-- models/                       # Models
|   |   |-- NAME.ex
|   |
|   |-- support/                      # Support modules
|   |   |-- NAME.ex
|   |
|   |-- templates/                    # Renderable templates
|   |   |-- VIEW_NAME                 # Templates for a view
|   |   |   |-- NAME.html.eex
|   |
|   |-- views/                        # Views
|   |   |-- NAME.ex
|   |
|   |-- gettext.ex
|   |-- router.ex                     # Defines routes
|   |-- web.ex                        # Defines models, controllers etc
|
|-- .codebeatignore                   # Things codebeat should ignore
|-- .editorconfig                     # Defines editor rules
|-- .gitignore                        # Things git should ignore
|-- .travis.yml                       # Configs travis runs
|-- apidoc.json                       # Configs apiDoc
|-- app.json                          # Configs review apps on Heroku
|-- elixir_buildpack.config           # Config for Heroku build
|-- mix.exs                           # Config for Elixir project
|-- mix.lock                          # Lockfile for Elixir deps
|-- nexpo.iml
|-- package-lock.json                 # Lockfile for npm
|-- package.json                      # Configs npm project
|-- phoenix_static_buildpack.compile  # Config for Heroku build
|-- phoenix_static_buildpack.config   # Config for Heroku build
|-- Procfile                          # Defines processes on Heroku
|-- README.md                         # Project README (this file)

Development

Setup environment

1. Make sure you have installed all system requirements. Then open a terminal and do the following steps
2. Install the following programs
   • npm - version 5 or higher. Installation instructions
3. Navigate yourself to the project root using the terminal.
4. Based on your running dist do one of the following:
   • Mac:
     • Execute make install-mac
   • Linux:
     • Open the following file: config/dev.exs
     • After poolsize: 10 , add username: "nexpo", password: "nexpo". Do not forget to add a , after poolsize.
     • Do the same thing for config/test
     • Execute make install-linux
5. Grab a cup of coffee!
6. Start the stack with npm run dev

Reset Linux environment

If you at any time need to reset your environment do the following: (NOTE THAT THIS WILL DROP ALL YOUR LOCAL DATA!)

1. Navigate to the project root using the terminal
2. Execute make fresh-install-linux
3. Grab a cup of coffee!
4. Start the stack with npm run dev

Implement things

Development lifecycle

1. Checkout and pull latest from master
2. Make a local branch with git checkout -b featurename
3. Install dependencies (if necessary) with npm run install-deps
4. Migrate or Reset database (if necessary) with mix ecto.migrate or mix ecto.reset
5. Populate database with mock data with mix run priv/repo/seeds.exs
6. Start the frontend and backend with npm run dev
7. Create your feature with TDD
8. Commit, and make a pull request
9. Wait for pull request to be accepted by someone
   • Review others pull requests
10. If pull request is merged, and all tests pass, your feature is automatically deployed to production

Testing

This project is developed with TDD.
This means that all code should be tested. We are urging all developers to follow this for the following reasons

• You will know for sure if you break anything when touching the code
• We are changing developers every year. You will make everything easier for the next team!

Recap of TDD:

1. Write a test
2. Make sure it fails
3. Implement code that makes it pass
4. Make sure your code is pretty and scalable

These are some commands to help you run all tests

Command	Description
npm run test	Runs all tests
npm run testwatch-backend	Starts testwatcher for backend

Writing tests for backend

All tests should be in the /test folder

You can define two different types of test cases

• Unauthenticated tests

test "name of the testcase", %{conn: conn} do
  # Write the test here. All requests will by a non-logged in user
end

• Authenticated tests

@tag :logged_in
test "name of the testcase", %{conn: conn, user: user} do
  # Write the test here. All requests will by the logged in user
end

Helpful things

Create a non-protected endpoint

1. Do not pipe it through api-auth in router

def CONTROLLER_METHOD_NAME(conn, params) do
  # params: http request parameters recieved
end

Create a protected endpoint

1. Pipe it through api-auth in router

use Guardian.Phoenix.Controller

def CONTROLLER_METHOD_NAME(conn, params, user, claims) do
  # params: http request parameters recieved
  # user: logged-in user
end

Dev servers

Command	Description
npm run dev	Start frontend and backend

• Backend server is run on localhost:4000
  • Visit localhost:4000/sent_emails to see emails sent in development
• Frontend server is run on localhost:3000
  • All api-calls are proxied transparently to the backend

Helpful scripts

Command	Description
npm run generate-docs	Generates documentation for HTTP API
npm run validate-editorconfig	Identifies breakage of editorconfig rules
npm run update-toc-readme	Updates Table of Contents in README
npm run download-prod-db	Replace development DB with production DB

Documentation

The HTTP API is documented using apiDoc. Documentation is changed in the code via special tags. More detailed information can be found here

See documentation generation instructions under Helpful scripts. Documentation can be found in docs/ directory

Setup your Editor

VS Code

• Install Prettier
• Install Eslint
• Install ElixirLS

Atom

• Install Prettier
• Install Eslint
• Install Elixir

Update your settings

• Enable "Set Editor Format On Save"
• Enable "Prettier Eslint Integration"

Deployment

The system is hosted at arkad-nexpo.herokuapp.com

Deployment is automatic from master branch. To deploy, you need only merge code into master branch via github.

Heroku

• Authenticated users will find the Heroku app here
• It uses the following buildpacks
  • Elixir buildpack
  • Phoenix static buildpack
• Phoenix provides good documentation of our setup here
• React frontend is automatically built on deploy with a custom setup of phoenix static buildpack
• Elixir and Erlang versions are specified in elixir_buildpack.config
• Node version is specified in phoenix_static_buildpack.config

Who do I contact?

• Joel Klint (Developer 2017)
• Oscar Rydh (Developer 2017)
• Victor Winberg (Scrum Master 2018)
• Anton Göransson (Developer 2018)
• Emma Asklund (Developer 2018)
• Martin Johansson (Developer 2018)
• Viktor Claesson (Developer 2018)
• Viktor Claesson (Internal Systems Manager 2019)
• Mustafa Albayati (Head Of IT 2020)