Development Environment

Install Compilers and Build Tools

  • Before anything else, do note that an antikythera instance and its gears run in the same ErlangVM cluster. Therefore, obviously, all development AND deployment environments must have the same Erlang and Elixir versions!
  • We strongly recommend asdf to manage this synchronization.

    • See antikythera’s .tool-versions file for the versions of Erlang and Elixir supported in current revision.

      • Antikythera itself has strict version checking mechanism and raises on compile if different versions are used in your environment.
      • (This may change later so that Erlang and Elixir versions can be checked by individual antikythera instances, not by antikythera)
  • Other requirements:

    • Some dependencies contain C source code and thus a reasonably new C compiler is required.
    • In macOS you may be warned by outdated GNU make version during compiling antikythera’s dependencies. In that case install GNU make using e.g. homebrew. The installed executable is gmake; create a symlink named make in somewhere in your $PATH so that the desired version of make command is selected.
    • Install development header of Expat, which is required by fast_xml library.

      • In macOS this should be already installed. If not, install expat with homebrew.
    • On Linux you have to install inotify-tools to enable file system watching tools such as exsync and mix_test_watch.
  • Install asdf as explained in the official README.md
  • Install asdf plugins

    • $ asdf plugin-add erlang
    • $ asdf plugin-add elixir
    • $ asdf plugin-add nodejs

      • Node.js installation is optional. You do not need it if you are not using asset-related features.
  • Install language versions

    • In order to invoke initial mix deps.get, you need to globally install reasonably new Erlang and Elixir versions.

      • $ asdf install erlang x.y.z && asdf global erlang x.y.z
      • $ asdf install elixir x.y.z && asdf global elixir x.y.z
    • Working on your antikythera instance:

      • If .tool-versions already exists, $ asdf install
      • If not,

        • $ asdf local erlang x.y.z && asdf local elixir x.y.z
        • then commit the generated .tool-versions file.
    • Working on a gear:

      • Make sure you have a valid symlink named .tool-versions which points to deps/your_antikythera_instance/.tool-versions

        • This way you can make your gear’s language versions in sync with your antikythera instance.
        • If your gear is generated using mix antikythera.gear.new, symlink to .tool-versions is automatically created.
      • $ asdf install

Shell history in iex

  • Although iex is able to remember commands executed in previous sessions, the feature is not enabled by default.
  • It is highly recommended to set the following environment variable during development:

    • export ERL_AFLAGS="-kernel shell_history enabled" (for bash family)

Prepare for Domain-based Routing

  • Antikythera routes web requests by subdomains and paths. See routing.
  • In local development, you must be able to resolve subdomain of localhost (e.g. your-gear.localhost) into loopback address (127.0.0.1).

    • The easiest way is to add a line like 127.0.0.1 your-gear.localhost to your /etc/hosts.
    • Alternatively, you can setup a local DNS server (such as dnsmasq) to resolve all subdomains of localhost.

Environment variables to tweak behavior of antikythera

  • In your local environment you can customize some of antikythera’s default settings using the following environment variables:

    • Runtime environment variables:

      • BASE_DOMAIN:

        • Suffix part of domain names to be used when clients interact with running gears. Defaults to localhost.
        • For example, when you are running :some_gear as BASE_DOMAIN=somedomain iex -S mix, you can browse the top page of the gear at http://some-gear.somedomain:8080/ (assuming that the default port number is used; see below).
        • Note that when using BASE_DOMAIN other than localhost, you may need to tell the DNS resolver on the client side about the gear’s domain name.
      • PORT:

        • Port number to receive incoming web requests from. Defaults to 8081 during mix test, and 8080 otherwise (thus one can run both iex -S mix and mix test at the same time).
        • Explicitly set this when you run multiple antikythera servers within your machine.
      • TEST_PORT:

        • Port number to send HTTP requests to during blackbox_local tests. Defaults to 8080.
      • NO_LISTEN:

        • A boolean flag for disabling web server functionality of antikythera. Defaults to false.
        • true is implicitly set when using Antikythera.Mix.Task.prepare_antikythera/0 in your mix task.
      • LOG_LEVEL:

        • Log level of all gears. Defaults to info. See also logging.
      • SOME_GEAR_CONFIG_JSON:

    • Compile-time environment variables: (to change the followings you need to recompile antikythera)

      • GEAR_ACTION_TIMEOUT:

        • Milliseconds to wait until gear action finishes. Defaults to 10000. See also controller.
      • GEAR_PROCESS_MAX_HEAP_SIZE:

        • Maximum size of per-process heap memory in words. Defaults to 50000000 (400MB in 64-bit architecture).