Skip to content

Latest commit

 

History

History
167 lines (101 loc) · 6.55 KB

README.md

File metadata and controls

167 lines (101 loc) · 6.55 KB
Raw

SurveyAPI

CircleCI License: MIT

SurveyAPI is an Elixir backend for SurveyJS, a Javascript library for creating online forms and surveys.

Web applications displaying surveys can use API calls to fetch survey definitions and store survey answers. Both surveys and answers follow a documented JSON format. Our backend store them in Postgres, using Postgres JSONB to make JSON search quick and painless.

Phoenix API generators were originally used to create the API. Here is the step-by-step description we used. The official Phoenix documentation has a long discussion about the use and limitations of generators. To summarize: you should not use generators without understanding what they do. Here are some tutorials for writing an API manually or using Phoenix 1.5 generators.

Prerequisites

Erlang and Elixir

Elixir requires the Erlang/OTP runtime. Current versions for this project can be found in the root level file .tool-versions. Please make sure the correct versions are installed. Using the asdf version manager to install and manage Erlang and Elixir is highly recommended for development. For production there are several other deployment alternatives.

Check your installation by running the commandline shell iex. The result should be similar to this:

Erlang/OTP 24 [erts-12.0.3] [source] [64-bit] [smp:12:12] [ds:12:12:10] [async-threads:1] [jit]

Interactive Elixir (1.12.2) - press Ctrl+C to exit (type h() ENTER for help)
iex(1)>

Phoenix

Phoenix is the Elixir web framework. First, make sure you have the latest version of Elixir and Erlang package managers.

mix local.hex
mix local.rebar

Then install the latest version of Phoenix.

mix archive.install https://github.com/phoenixframework/archives/raw/master/phx_new.ez

Postgres

Postgres 14 is currently used for development. At least one database user must have permissions to create databases.

On developer machines you can use a postgres user with password postgres (the default for new Elixir projects). In production, datatabase logins MUST be more secure. Phoenix by default keeps production login and other sensitive information in a file named prod.secret.exs. For security reasons, this file should not be kept under version control.

Note! Docker-based deployments use environment variables instead of 'prod.secret.exs'.

Development

Test installation on development machine

Clone this repository

  git clone https://github.com/kamidev/survey_api.git
  cd survey_ap

Install dependencies

mix deps.get

Setup SSH for development. See https://hexdocs.pm/phoenix/using_ssl.html#ssl-in-development

mix phx.gen.cert

Wipe the dev database clean and load some sample data

mix ecto.reset

Start the Phoenix server

iex -S mix phx.server

Then check the API endpoints from another terminal.

curl https://localhost:4001/api/surveys -k
curl https://localhost:4001/api/answers -k

After a clean installation, both endpoints return {"data":[]}. If the database already has some content, some JSON data will be returned.

You can also check the API using your browser.

https://localhost:4001/api/surveys

https://localhost:4001/api/answers

Note! Make a browser security exception for Elixir's self-certified SSL certificates if necessary.

Automatic checking of source code dependencies

This repo uses Github Dependabot to check for updated dependencies. Pull requests for updated dependencies will be generated automatically

Automated code quality tools

Currently, the following tools are configured:

credo - static code analysis tool with a focus on teaching and code consistency

dialyxir - code analysis using Dialyzer

ex_doc - produce HTML and EPUB documentation

ex_unit - unit testing framework

formatter - built-in automatic code formatter

sobelow - security-focused static analysis of Phoenix Framework

A single mix task is used to run all these tools :

➜ mix check

Sample session:

... lots of detailed output omitted here

=> finished in 0:15

✓ compiler success in 0:05
✓ credo success in 0:01
✓ dialyzer success in 0:10
✓ ex_doc success in 0:03
✓ ex_unit success in 0:08
✓ formatter success in 0:01
✓ sobelow success in 0:02

Please make sure the ex_check library is installed and correctly configured to get the most out of mix check.

Building releases for production use

To deploy SurveyAPI in production, we use an Elixir release. Here is a short tutorial about that.

Typically, you first test your release on a developer machine. To build a production release, first run:

MIX_ENV=prod mix release

If this succeeds, you will see a message describing various options for running the release. Try running it in the background:

_build/prod/rel/survey_api/bin/survey_api daemon

Verify that localhost:4000/api/surveys and other endpoints produce valid JSON. Then run mix check and deal with any problems reported by the automated tools.

Once the release is good enough for production, commit and push the latest code.

Deployment

Read more about deployment, server configuration and using systemd services here.