Development Quickstart

Development Quickstart

You will need a working Go and Node.js environment. Installing Swaks is recommended to generate test mail.

Note: While it is possible to develop on Windows; Linux or Mac OS is required to use most of our helper scripts.

Initial build

Checkout the source:

git clone https://github.com/inbucket/inbucket.git
cd inbucket

Build the backend (will fetch Go dependencies):

make

Install JavaScript dependencies and build the web UI:

cd ui
yarn install
yarn build

Verify Inbucket starts and that the web UI loads:

cd ..
./inbucket

You should see a handful of INF log lines but no errors. Point your web browser at http://127.0.0.1:9000/ then select the Status tab. If everything loaded, then congratulations, you have a locally compiled build running!

As we did not pass any specific configuration options to Inbucket, it is using memory storage (instead of files on disk), and will be empty each time we restart the inbucket process. Let's look at a better workflow...

Backend development

Terminal 1

From the root inbucket directory, run make to clean, test and compile the backend. Then it with reasonable development configuration:

make
etc/dev-start.sh

Note: The dev script will abort if the web UI index.html file is not found.

This will launch Inbucket with a development friendly configuration with debug logging and storing mail in /tmp/inbucket. The retention period is reduced to 3 hours to encourage you to send in fresh mail periodically.

Point your web browser at http://0.0.0.0:9000/ then select the Monitor tab.

Terminal 2

Send some test messages (requires Swaks to be installed):

etc/swaks-tests/run-tests.sh

You should see the emails listed in your web browser, as well as a bunch of Inbucket debug logging in Terminal 1.

After you make changes to the backend, kill the inbucket process and repeat the steps above to test it.

Note: The integration tests start an Inbucket server using the default ports. The test will fail if you already have an Inbucket (or another) process holding those ports.

Frontend development

Frontend development still requires a running backend, so follow the Terminal 1 steps in the backend section before proceeding.

Terminal 3

Build & launch the frontend in development mode:

cd ui
yarn start

If your browser does not open automatically, visit http://0.0.0.0:1234/ and select the Monitor tab. Follow the steps for Terminal 2 in the backend section to send some messages into Inbucket and confirm they appear in your browser.

The development server features hot code loading, so most changes you make to the Elm code will not require a browser refresh to be visible.

Docker container build

Build the container from the root inbucket directory:

docker build . -t inbucket/inbucket:edge

The Dockerfile uses a multi-stage build, the first container installs all the Go and Elm dependencies and builds Inbucket. The output of the build is then copied to a minimal container.

To test the docker container locally, you can use our helper script:

etc/docker/docker-run.sh

which is equivalent to the following docker command:

docker run -p 9000:9000 -p 2500:2500 -p 1100:1100 \
  -v /tmp/inbucket/config:/config \
  -v /tmp/inbucket/storage:/storage \
  inbucket/inbucket:edge

This forwards the default HTTP (9000), SMTP (2500) and POP3 (1100) ports into the container, and maps the storage volumes into /tmp/inbucket. Using the same default ports means you can still run etc/swaks-tests/run-tests.sh to populate it with email.

Note: the log output from the Docker container defaults to a more verbose JSON format, this is intentional.