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 namedmake
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.
- In macOS this should be already installed. If not, install
- 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.
- If
Working on a gear:
Make sure you have a valid symlink named
.tool-versions
which points todeps/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.
- The easiest way is to add a line like
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
asBASE_DOMAIN=somedomain iex -S mix
, you can browse the top page of the gear athttp://some-gear.somedomain:8080/
(assuming that the default port number is used; see below). - Note that when using
BASE_DOMAIN
other thanlocalhost
, you may need to tell the DNS resolver on the client side about the gear’s domain name.
- Suffix part of domain names to be used when clients interact with running gears. Defaults to
PORT
:- Port number to receive incoming web requests from. Defaults to
8081
duringmix test
, and8080
otherwise (thus one can run bothiex -S mix
andmix test
at the same time). - Explicitly set this when you run multiple antikythera servers within your machine.
- Port number to receive incoming web requests from. Defaults to
TEST_PORT
:- Port number to send HTTP requests to during
blackbox_local
tests. Defaults to8080
.
- Port number to send HTTP requests to during
NO_LISTEN
:- A boolean flag for disabling web server functionality of antikythera. Defaults to
false
. true
is implicitly set when usingAntikythera.Mix.Task.prepare_antikythera/0
in your mix task.
- A boolean flag for disabling web server functionality of antikythera. Defaults to
LOG_LEVEL
:- Log level of all gears. Defaults to
info
. See also logging.
- Log level of all gears. Defaults to
SOME_GEAR_CONFIG_JSON
:- Gear config of
:some_gear
. See also gear_config.
- Gear config of
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.
- Milliseconds to wait until gear action finishes. Defaults to
GEAR_PROCESS_MAX_HEAP_SIZE
:- Maximum size of per-process heap memory in words. Defaults to
50000000
(400MB in 64-bit architecture).
- Maximum size of per-process heap memory in words. Defaults to