Getting started

BullMQ Proxy is delivered as a docker image, you can find all the images in Githubs container registry:

GitHubGitHub

BullMQ Proxy container registry

You can the proxy directly by starting a container based on the image, but the easiest way is to use the following docker-compose.yaml:

version: '3'
services:
  proxy:
    image: ghcr.io/taskforcesh/bullmq-proxy:latest
    ports:
      - 8080:8080
    environment:
      PORT: 8080
      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_PASSWORD: ${REDIS_PASSWORD}
      REDIS_TLS: ${REDIS_TLS}
      AUTH_TOKENS: ${AUTH_TOKENS}
  redis:
    image: 'redis:alpine'

You can also have a local .env file with some secrets so that you can start testing the proxy, for example:

AUTH_TOKENS=1234

Will set a test token "1234" that you can use to authenticate when interacting with the proxy. There are several environment variables that can be used to configure different aspects of the proxy. You can find all of them here.

You can start the proxy now with docker-compose up:

$ docker-compose up
WARN[0000] The "REDIS_PASSWORD" variable is not set. Defaulting to a blank string.
WARN[0000] The "REDIS_TLS" variable is not set. Defaulting to a blank string.
[+] Running 2/2
 ✔ Container bullmq-proxy-proxy-1  Created                                                                                                                                                                                    0.0s
 ✔ Container bullmq-proxy-redis-1  Created                                                                                                                                                                                    0.0s
Attaching to proxy-1, redis-1
redis-1  | 1:C 28 Feb 2024 14:11:32.929 # WARNING Memory overcommit must be enabled! Without it, a background save or replication may fail under low memory condition. Being disabled, it can also cause failures without low memory condition, see https://github.com/jemalloc/jemalloc/issues/1328. To fix this issue add 'vm.overcommit_memory = 1' to /etc/sysctl.conf and then reboot or run the command 'sysctl vm.overcommit_memory=1' for this to take effect.
redis-1  | 1:C 28 Feb 2024 14:11:32.934 * oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo
redis-1  | 1:C 28 Feb 2024 14:11:32.934 * Redis version=7.2.1, bits=64, commit=00000000, modified=0, pid=1, just started
redis-1  | 1:C 28 Feb 2024 14:11:32.934 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf
redis-1  | 1:M 28 Feb 2024 14:11:32.940 * monotonic clock: POSIX clock_gettime
redis-1  | 1:M 28 Feb 2024 14:11:32.972 * Running mode=standalone, port=6379.
redis-1  | 1:M 28 Feb 2024 14:11:32.982 * Server initialized
redis-1  | 1:M 28 Feb 2024 14:11:32.993 * Loading RDB produced by version 7.2.1
redis-1  | 1:M 28 Feb 2024 14:11:32.995 * RDB age 228268 seconds
redis-1  | 1:M 28 Feb 2024 14:11:32.995 * RDB memory usage when created 0.88 Mb
redis-1  | 1:M 28 Feb 2024 14:11:32.995 * Done loading RDB, keys loaded: 0, keys expired: 0.
redis-1  | 1:M 28 Feb 2024 14:11:32.995 * DB loaded from disk: 0.012 seconds
redis-1  | 1:M 28 Feb 2024 14:11:32.996 * Ready to accept connections tcp
proxy-1  | $ bun src/index.ts
proxy-1  |
proxy-1  | ;
proxy-1  | ;:                                             ;:
proxy-1  | :;              :;++;. ::.                     ;:
proxy-1  | .:;.          :X&X$&$$$;$&&&X+:                .;:
proxy-1  | ::$XxX$$&&&&&&&;+X$$&$++XX$XX++$$x+;::       :x.:
proxy-1  | :::+XXXx+x+++++:XXXX$$+;X$X$++:XXXX$$&&&&&&&&X:;.
proxy-1  |   :;:::::;;:.  +++$$X$X;xXXXX::..:...::;+++;::;
proxy-1  |        ;+::. ;.:XX+XxXX;X$$Xx;.:.:;X:   ...
proxy-1  |          x:::. :.++:X$XxxX$$xx    :;
proxy-1  |         +$Xx: .XX+.:++$$$x;;:; .+X&:
proxy-1  |         X$x;:::+;+;.+X$$$X;:::.::+X&$.
proxy-1  |         xX+;+::+;x++++X$$x:;:;.;.:+X+XX;
proxy-1  |         xx:+:;.;;.++++$$$x;;;.:.;:.xx;++$$x::;;;.
proxy-1  |         x+;;;:::;+;X$xXXXXX: :::.::+$x .:+$&&&&&&&;
proxy-1  |        +$;;;;:::. +x:+++++;X .:::.+:+x$+&&X$;XX;++$&&;
proxy-1  |       +$X+::;::::.;+::   ::X ::. :.;$&x+$$X&$$&&; +$x++
proxy-1  |      ;&$$X::;:;    ::::.::: .:: ::;X$&$X+$:+&Xx$$+ :.;X:
proxy-1  |      X$X$$+:.:::         .  ::...++XX$Xx;X:X&$++x::XX;+++
proxy-1  |     .X$;x+;::.+:.       :  . .::;x+x:XXx:::X$$+++ :+X$;+x+
proxy-1  |      +Xx:X; :::::: :.  :   :: +;+X+;.+++. x+$X+++.X$+;:;xX:
proxy-1  |      ;:;: ::.:. : :. .     :::;+++:. ::. :;:+;;+:.X&$x;.;x;
proxy-1  |       :..:.::.  : ...    ...:;;::. :;   ::.:.;+:..+XX;:::;:
proxy-1  |       :;.:::.:. ..   ..  .:::;. .;x$Xx    ..::..  :;:.;+x:.
proxy-1  |       $&;. .:.  ::  ::   .. :.  ;x$x:$;   .::.     . ::+;::
proxy-1  |      :&x++.     .:. ;:  :::   ::+$X:.x; .::     ... ..:. ::+
proxy-1  |       $;+X;..:  . . +:  ..  .+x;Xx:;.:.      . .  ..:  .:: :+
proxy-1  |       ;+:++; .:. :. ;.      .;:.::X;.; ....   .      .:;;   :x
proxy-1  |        :;:..   . :::         ..;.;: ;.. .:  :    . .:::XX.   :x:
proxy-1  |         :::.:.   .::.       .:+::.::;. ::  :     ;. .::::     :+
proxy-1  |          .;;:...  ::::...  :+Xx. ::.;;: .  +      ::.. ...    +x;
proxy-1  |           +$X;            :+$$X:.    :::. :++          .::  ++X++
proxy-1  |           ;+::.;.         :+. ;++:     ::. :+:      :: .:: :x;.;;.
proxy-1  |            ;:...           :::.:;      .x:.:         : .:.::;+;:+
proxy-1  |            ;..:             ::..       X;..           :.; ::;;;;;
proxy-1  |           :X;:.            :x+:.      +x::            ::;  ;;:+:
proxy-1  |          .$$x::           .$$X::     +X::            :::;   ;;;;.
proxy-1  |         .;;;::..          +;;;::    x+;::           :::::: .;:;
proxy-1  |        .X:Xx;..          X+.x+;:   +;+;:           .+:;+;   ..:
proxy-1  |       .X;XX;:::         X+:xX+:.  x;;+:.           X;:x;::
proxy-1  | .:;+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++:..
proxy-1  |     ..:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
proxy-1  | [1709129499052][INFO] BullMQ Proxy: Running BullMQ Proxy on port 8080 (c) 2024 Taskforce.sh Inc. v0.1.0

The proxy will now be ready to accept calls, for instance we could try to get all the jobs in a given queue:

$ curl --location 'http://localhost:8080/queues/my-test-queue/jobs' \
--header 'Authorization: Bearer 1234'

Will return:

Not found%

as there are no jobs in any queue yet. Please check the following sections in order to learn how to use all the proxy's features.