IronMQ On-Premise - Single Node Installation
This guide will show you how to install and configure a single, full featured IronMQ node. This is the first step to install your IronMA HA cluster.
1. Pull Docker images
IronMQ HA requires 2 major components running at all times. We provide docker images for both:
iron/mq- the core queue database
iron/auth- user & project storage, authentication and authorization
Download those docker images with the following:
docker pull iron/mq docker pull iron/auth
2. Run the Docker images
Use the following commands to run the Docker images that you just pulled:
docker run --name=ironmq -d -p 8080:8080 --net=host iron/mq docker run --name=ironauth -d -p 8090:8090 --net=host iron/auth
These commands start the queue database and auth server, respectively. If you’re
familiar with Docker, you can run without
--net=host, but you’ll have to
iron/mq container to
iron/auth with a different method. Please see configuration for more on that topic.
Additionally, there are a wide variety of Docker CLI flags that you can use to further customize. Please see the CLI reference for more details.
We’ve listed a few below:
-druns as daemon, omit to run in foreground
-p HOST:CONTAINERbinds to port on host machine
--net=hostuses the host machine’s network interface
Note: when you’re ready to stop IronMQ, simply run:
docker stop ironmq docker stop ironauth
Note: Data storage
As mentioned in other sections, IronMQ persists messages until they’ve been completely processed. In the above setup, user, project, message and other data are stored ephemerally inside the applicable containers.
That means that when you shut down the
iron/mq container, for example, you will
lose all unprocessed messages.
If you would like to persist the data, we suggest that you create a persistent
data volume container that
iron/mq mounts on startup. Below is a brief
example. See the
for more details.
# create the data container, mounted on host at /mnt/data # note: ironmq and ironauth both store their data at /ironmq/data in container by default docker run --name irondata -v /mnt/data:/ironmq/data busybox true # run mq with data volume docker run -d --volumes-from irondata -p 8080:8080 iron/mq
3. Create a new user and project
The IronMQ API requires a user token and a project ID to post a message onto the queue.
First, create a user:
docker run --net=host iron/authcli iron -t adminToken create user $USER_EMAIL $USER_PASSWORD
If this succeeded, you’ll see a log message that looks like this:
INFO[04-10|20:13:45] user created successfully id=55282ef9b1a1940006000003 email=$USER_EMAIL token=$USER_TOKEN
$USER_TOKEN, then create a new project with it:
docker run --net=host iron/authcli iron -t $USER_TOKEN create project $PROJECT_NAME
$PROJECT_NAME into an
iron.json file or environment
variables. The format of the file or variables is specified in the client libraries
4. Post messages to IronMQ
You are now ready to use client libraries or APIs to enqueue and dequeue messages.
TODO: these links are broken
5. Next steps
You now have a single IronMQ node up and running. After you’re comfortable doing operations on your queues, we recommend that you read our instructions on setting up an HA cluster.
If you find issues are problems during your setup, please contact us at firstname.lastname@example.org and we’d be happy to help.