Skip to content

Latest commit

 

History

History
213 lines (148 loc) · 9.81 KB

INSTALL.md

File metadata and controls

213 lines (148 loc) · 9.81 KB
Raw

Azimutt installation guide

Follow this guide to install Azimutt, the all-in-one app to explore and understand your database.

Architecture

Azimutt is a web application written with Elixir/Phoenix for the backend and Elm/TypeScript for the frontend. It's backed by a PostgreSQL database and a file storage with a S3 API. It also needs an email service for account validation, password reset and organization invitation, we currently support smtp, gmail and mailgun providers, but we could add more if you need.

There is also a Node.js server, the gateway, to proxy calls to your databases. You can install it on your infrastructure or let users call it from Azimutt CLI.

Installation

Pre-build Docker image

Make sure you have Docker installed on your local machine, refer to the official Docker documentation to install it if needed.

Disclaimer: our pre-build image is made for Linux environment. If you need Mac or Windows, please reach out.

Step 1: Pull the Docker image

Pull the Docker image from the registry:

docker pull ghcr.io/azimuttapp/azimutt:main

Step 2: Run the Docker container

Now, we'll need to run the container using the image we've just pulled. But just before, you need to configure environment variables and give them to your Docker container. For that you can use the --env-file option with a the .env.example file set up with your configuration.

docker run -d --name azimutt \
--env-file <path_to_your_env_file> \
-p 4000:4000 \
ghcr.io/azimuttapp/azimutt:main

The Azimutt application should now be running on http://localhost:4000.

Build your own Docker image

Make sure you have Docker installed on your local machine, refer to the official Docker documentation to install it if needed.

Disclaimer: our Docker image is made for Linux environment. If you need Mac or Windows, please reach out.

Step 1: Clone the Azimutt repository

Clone the Azimutt repository on your local machine:

git clone git@github.com:azimuttapp/azimutt.git

Step 2: Set up environment variables

Define your environment variables, you can copy the .env.exemple to .env and edit it with your values:

cp .env.example .env

On linux and Windows remove the export in front of the variables in the file.

Step 3: Build the Docker image

docker build -t azimutt:latest .

Step 4: Run the Docker container

Now, we'll need to run the container using the image we've just built. We'll use the --env-file option to supply your environment variables to the container:

docker run -d --name azimutt \
--env-file <path_to_your_env_file> \
-p 4000:4000 \
azimutt:latest

The Azimutt application should now be running on http://localhost:4000.

Bare metal installation

TODO

But in short you will have to install Elixir & Elm on your machine and launch the backend. Contact us if you need it, we will write this guide on demand 😉

Environment variables

Here is the full list of environment variables you can use to set up Azimutt application.

Technical requirements

These are the basic variables you will need to set up Azimutt:

  • PHX_SERVER (optional): if true, start the Phoenix server in server mode
  • PHX_HOST (required): host of the deployed website (ex: localhost or azimutt.app), it's used to build absolute urls
  • PORT (required): the port the server will listen to (ex: 4000)
  • SECRET_KEY_BASE (required): the secret used for server encryption (cookies and others), should be at least 64 bytes and you probably want a random value for it
  • DATABASE_URL (required): the whole url to connect to your PostgreSQL database (ex: postgresql://<user>:<pass>@<host>:<port>/<database>)
    • DATABASE_IPV6 (optional): if true, the database driver will use IPV6
    • DATABASE_POOL_SIZE (optional, default: 10): the database connection pool size
    • DATABASE_ENABLE_SSL (optional): if true, the database driver will require SSL
  • FILE_STORAGE_ADAPTER (required, values: local or s3): file storage is used to store project json files
    • if s3
      • S3_BUCKET (required): the bucket used to store project json
      • S3_HOST (optional): the s3 host (if you don't use s3 profiles)
      • S3_KEY_ID & S3_KEY_SECRET (optional): credentials to connect to the s3 (if you don't use s3 profiles)
      • S3_FOLDER (optional): if you want to store Azimutt files in a specific folder inside your bucket
      • S3_REGION (optional, default: eu-west-1): to specify your AWS region
  • EMAIL_ADAPTER (optional, values: mailgun, gmail or smtp): the service to use to send emails (email confirmation, password reset & organization invitations), contact us of you need another integration
    • if mailgun
      • MAILGUN_DOMAIN (required)
      • MAILGUN_API_KEY (required)
      • MAILGUN_BASE_URL (required)
    • if gmail
      • GMAIL_ACCESS_TOKEN (required)
    • if smtp
      • SMTP_RELAY (required)
      • SMTP_USERNAME (required)
      • SMTP_PASSWORD (required)
      • SMTP_PORT (required)
  • SUPPORT_EMAIL (optional, default contact@azimutt.app): email shown in Azimutt when users need support
  • SENDER_EMAIL (optional, default contact@azimutt.app): email Azimutt will us to send emails

Key features

At least one of authentication methods should be defined:

  • AUTH_PASSWORD (optional): if true, enable email/password authentication
  • AUTH_GITHUB (optional): if true, enable GitHub sso
    • GITHUB_CLIENT_ID (required)
    • GITHUB_CLIENT_SECRET (required)

Optional features & services

  • GATEWAY_URL (optional): if you deployed the gateway, the url where it can be reached out
  • SKIP_ONBOARDING_FUNNEL (optional): if true, users will not go through the onboarding funnel on account creation
  • SKIP_EMAIL_CONFIRMATION (optional): if true, users will not be asked to confirm their email (either blocked or soft)
  • REQUIRE_EMAIL_CONFIRMATION (optional): if true, users will not be allowed to use Azimutt until they confirm their email, otherwise they will have a soft confirmation banner
  • REQUIRE_EMAIL_ENDS_WITH (optional): force all users to use an email ending with a suffix, your domain name for example
  • ORGANIZATION_DEFAULT_PLAN (optional, values: free or pro): define the plan an organization has by default when created
  • GLOBAL_ORGANIZATION (optional): an organization id, if set, all new users will be added to this organization
    • GLOBAL_ORGANIZATION_ALONE (optional): if true, only the global organization is shown (allows to work like a mono-tenant app)
  • SENTRY (optional): if true, add Sentry integration
    • SENTRY_BACKEND_DSN (optional): your Sentry DSN (ex: https://2g4ks8n9zxeqkfzven08yvayzz1bol0x@062prn3b.ingest.sentry.io/6050617)
    • SENTRY_FRONTEND_DSN (optional): your Sentry DSN (ex: https://qo83sgd9ojxwpydce1am5byd2o1y86zi@zqwwq6tu.ingest.sentry.io/8470350)
  • TWITTER (optional): if true, allow to use Twitter API to fetch tweets & unlock features (change table color)
    • TWITTER_CONSUMER_KEY (required)
    • TWITTER_CONSUMER_SECRET (required)
    • TWITTER_ACCESS_TOKEN (required)
    • TWITTER_ACCESS_SECRET (required)

Other features you will probably not need

  • PUBLIC_SITE (optional): if true, will show the public site, otherwise home will redirect to login page (you probably don't want it)
  • GITHUB (optional): if true, allow to use GitHub API, no real usage for now
    • GITHUB_ACCESS_TOKEN (required)
  • POSTHOG (optional): if true, enable PostHog integration
    • POSTHOG_HOST (required)
    • POSTHOG_KEY (required)
  • BENTO (optional): if true, forward events to Bento
    • BENTO_SITE_KEY (required)
    • BENTO_PUBLISHABLE_KEY (required)
    • BENTO_SECRET_KEY (required)
  • STRIPE (optional): if true, allow to purchase plans with Stripe, you probably don't need it ^^
    • STRIPE_API_KEY (required): Stripe api key (ex: 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)
    • STRIPE_WEBHOOK_SIGNING_SECRET (required): Stripe webhook secret (ex: whsec_ayZAyKqOLy34UKNeI3eq4icXVWJam0IW)
    • STRIPE_PRICE_PRO_MONTHLY (required): the Stripe price for the pro plan (ex: price_uJINukB78aAbajUQHy6Ra523)
  • CLEVER_CLOUD (optional): if true, enable auth & hooks for Clever Cloud Add-on
    • CLEVER_CLOUD_ADDON_ID (required)
    • CLEVER_CLOUD_PASSWORD (required)
    • CLEVER_CLOUD_SSO_SALT (required)
  • HEROKU (optional): if true, enable auth & hooks for Heroku Add-on
    • HEROKU_ADDON_ID (required)
    • HEROKU_PASSWORD (required)
    • HEROKU_SSO_SALT (required)

Never share your secrets or keys in public spaces.