Need help with alpine-sqs?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

186 Stars 36 Forks GNU Affero General Public License v3.0 21 Commits 21 Opened issues


Dockerized ElasticMQ server + web UI over Alpine Linux for local development

Services available


Need anything else?

Contributors list

Alpine SQS (alpine-sqs)


Docker Pulls Docker Pulls standard-readme compliant

Dockerized ElasticMQ server + web UI over Alpine Linux for local development.

Alpine SQS provides a containerized Java implementation of the Amazon Simple Queue Service (AWS-SQS). It is based on ElasticMQ running Alpine Linux and the Oracle Java 8 Server-JRE. It is compatible with AWS's API, CLI as well as the Amazon Java SDK. This allows for quicker local development without having to incurr in infrastructure costs.

The goal of this repository is to maintain an updated Docker environment for ElasticMQ with an integrated web UI for visualizing queues and messages.

Table of Contents


When searching for existing local implementations of SQS I came across a Docker image by @vsouza called docker-SQS-local with over 11K pulls at the time.

This introduced me to ElasticMQ, which this project is based on and is described by it's creators as:

a message queue system, offering an actor-based Scala and an SQS-compatible REST (query) interface.

Using his work as inspiration I decided to improve upon it by implementing the following:

  • Reduce the Docker image foot-print as much as possible.
  • Automatically update to the latest ElasticMQ server.
  • Integrated UI for message-queue visualization.
  • Automatic tests & builds (work in progress).
  • Thorough documentation.

See also

For more information on the different projects this work is based on, please visit:



To be able to use this environment, please make sure you have installed the latest version of Docker.

If you intend to build the environment yourself, it is recommended that you also install the latest version of Docker Compose.

Installation methods

You can obtain the environment in two ways; The easiest is to pull the image directly from Docker Hub. Also, you may clone this repository and build/run it using Docker Compose.

1. Pulling from Docker Hub

docker pull roribio16/alpine-sqs

2. Building from scratch

git clone


Running the environment

Depending on how you chose to install the environment, you can initialize it in three ways:

docker run

Use this method if you're pulling directly from Docker Hub and do not have a

docker run --name alpine-sqs -p 9324:9324 -p 9325:9325 -d roribio16/alpine-sqs:latest

Custom configuration files may be used to override default behaviors. You can mount a volume mapping the container's

directory to a folder in your host machine where the custom configuration files are stored.

Providing for sake of example that in your host machine directory

you have both
files, you can run the container with:
docker run --name alpine-sqs -p 9324:9324 -p 9325:9325 -v /opt/alpine-sqs:/opt/custom -d roribio16/alpine-sqs:latest

For any configuration file not explicitly included in the container's

will fall back to using the default configuration files listed here.

docker-compose up

If you've cloned the repository you can still take advantage of the image present in Docker Hub by running the container from the default

file. This will pull the pre-built image from the public registry and run it with the same values stated in the previous method.
docker-compose up -d

docker-compose up --build

To build the image from scratch and then run the corresponding container, use this method.

docker-compose -f up -d --build

Note: To use any of the Docker Compose methods, you need to clone this repository as well as have Docker Compose installed.

Note 2: Depending on your platform, you may need to adjust how you declare mounted volumes. You can find instructions for your specific platform here.

Working with queues

ElasticMQ provides an Amazon-SQS compatible interface. This means you may use the AWS command-line tool, API calls and the Java SDK, to interact with local queues the same as if interacting with the actual SQS.

Default queue

The default configuration provisions ElasticMQ with a initial queue of the same name at run time. This allows you to start pushing messages to the queue without further configuration.

To make use of this queue, point your client to:


Dead letter queue

The default dead letter queue is called dlq, configured in opt/elasticmq.conf

Sending a message

To send messages to a queue you need to specify the new endpoint url and queue url along with the message payload. The following example uses the AWS CLI to send a message to the

aws --endpoint-url http://localhost:9324 sqs send-message --queue-url http://localhost:9324/queue/default --message-body "Hello, queue!"

Viewing messages

To view messages, navigate to the web UI (sqs-insight) by pointing your web browser to


You can also poll for messages from the command-line like so:

aws --endpoint-url http://localhost:9324 sqs receive-message --queue-url http://localhost:9324/queue/default --wait-time-seconds 10

Creating new queues

You can create new queues by using the command-line or configuring ElasticMQ directly.

aws --endpoint-url http://localhost:9324 sqs create-queue --queue-name newqueue
Edit ElasticMQ configuration file

Navigate to the directory where the configuration files reside and edit the

file to add a new entry for each queue to the
queues {
    default {
        defaultVisibilityTimeout = 10 seconds
        delay = 5 seconds
        receiveMessageWait = 0 seconds
    newqueue {
        defaultVisibilityTimeout = 10 seconds
        delay = 5 seconds
        receiveMessageWait = 0 seconds

Note: The configuration directory location inside the container is located at

. If you mounted that volume onto your host, you can also find the configuration files there.

After editing the

file, you need to restart the ElasticMQ server by running the
supervisorctl restart elasticmq
command inside the container. If you're editing the configuration file outside of the container, use this command:
docker exec -it alpine-sqs sh -c "supervisorctl restart elasticmq"

Registering new queues with the UI

To be able to visualize newly created queues, you need to edit the

file to register the new queue with the UI server. Edits to this file are automatically detected by the server and does not require a restart.

Configure a new endpoint like this:

"endpoints": [
           "key": "notValidKey",
           "secretKey": "notValidSecret",
           "region": "eu-central-1",
           "url": "http://localhost:9324/queue/default"
           "key": "notValidKey",
           "secretKey": "notValidSecret",
           "region": "eu-central-1",
           "url": "http://localhost:9324/queue/newqueue"

All the fields, except the

field, are required by
to function but are not used when pointing it to a local queue server. This means that the values in those fields are not relevant for the UI to work correctly.

Consult the AWS CLI Command Reference or the AWS SDK for Java guide for more examples and information.


Ronald E. Oribio R. - @roribio.


PRs are accepted and encouraged!

Please direct any questions, requests, or comments to the Issues section of this project.

Note: If editing this Readme, please conform to the standard-readme specification.


Copyright 2017 Ronald E. Oribio R.

This project is licensed under the GNU General Public License, version 3.0. See the LICENSE file for details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.