Oxidux

Proxy server and process manager for developing web apps inspired by invoker and overmind.

Warning this is still very much a work in progress, there are a lot of rough edges.

Installation

HomeBrew or LinuxBrew:

brew tap jonmast/oxidux https://github.com/jonmast/oxidux.git
brew install oxidux

Manual: Download the latest release for your platform and place it in your PATH.

Note: Windows isn't supported at this time, but I'm happy to assist if someone wants to work on porting it.

You'll also need:

• Tmux - all apps are run within a tmux session.

Setup

Linux

DNS Resolution

The dev-tld-resolver tool is recommended for resolving *.test domains to localhost. You'll need to add test to the DEV_TLD_DOMAINS environment variable to enable support for .test domains.

Service management

Oxidux can be run manually from the terminal, but using SystemD socket activation is recommended. See example socket and service files.

These files should be added to the /etc/systemd/system/ directory and enabled with the following commands:

sudo systemctl daemon-reload
sudo systemctl enable oxidux.socket
sudo systemctl start oxidux.socket

MacOS

DNS Resolution

Oxidux has a builtin DNS resolver. Add the following config to /etc/resolver/test:

nameserver 127.0.0.1
port 6153

Service management

Starting via Launchd is recommended. See example plist file.

The plist file should be added to ~/Library/LaunchAgents/ and loaded with the following command:

launchctl load ~/Library/LaunchAgents/oxidux.plist

Configuration

# config.toml

[general]
# The proxy server will run on this port. Ignored if socket activation is used.
proxy_port = 80
# DNS server port for MacOS. Also ignored with socket activation.
dns_port = 6153
# TLD for apps. Defaults to "test".
domain = "test"

App configuration

Each app should have a config file in ~/.oxidux/apps. Example:

# ~/.oxidux/apps/my-app.toml

# Unique identifer and domain for app (this will be available at "my-app.test")
name="my-app"
# App root directory
directory = "/path/to/app/"
# Commands to start app processes
# dynamically generated port is passed in as an environment variable
commands = { web = "scripts/server -p $PORT", worker = "scripts/worker" }
# Alternatively, load commands from Procfile on app directory
procfile = true
# Alternate domains for app
aliases = ["othername", "yetanother"]

Usage

Restart a process

From the app directory, run

oxidux restart     # Restart all processes for app
# Or
oxidux restart web # Restart just the process named "web"

The terminal will be connected to the Tmux session for that process.

Connect to process session

From the app directory, run

oxidux connect web

Connects to the Tmux session for a given process. If the process name is omitted the first process for the app will be used.

License

Licensed under GPL version 3 or later, see LICENSE.