Connect to Redis in Docker or Homebrew on your Mac

What you need

Redis running on your Mac, in Docker or from Homebrew. Pick one: both want port 6379.

In Docker

docker run --name redis -p 127.0.0.1:6379:6379 -d redis:8

-p 127.0.0.1:6379:6379 publishes the port on your Mac’s loopback address only. The shorter -p 6379:6379 publishes it on every network interface of your Mac, and Docker’s documentation warns that a port published that way is reachable from outside your machine. With no password, that means anyone on the same network.

The redis:8 image was Redis 8.10.2 when we checked. It includes the data types that Redis 8 ships in Redis Open Source (search, JSON, time series and probabilistic structures); its startup log lists them as the bf, search, timeseries and ReJSON modules. Since Redis 8.0, Redis Open Source can be used under the AGPLv3 as well as the RSALv2 and SSPLv1 licences.

Keep your data. Redis keeps its files in /data inside the container, which disappears with the container unless it’s a volume. By default the image saves a snapshot on Redis’s standard schedule (save 3600 1 300 100 60 10000: after an hour if one key changed, five minutes if 100 did, one minute if 10,000 did). To log every write as well, turn on the append-only file:

docker run --name redis -p 127.0.0.1:6379:6379 -v redis-data:/data -d redis:8 \
  redis-server --appendonly yes

On a container started like this, /data/appendonlydir held appendonly.aof.1.base.rdb, appendonly.aof.1.incr.aof and appendonly.aof.manifest, and appendfsync was everysec: the log is flushed to disk once a second.

With Homebrew

brew install redis
brew services start redis

brew services start runs the server now and at every login. Homebrew’s formula was Redis 8.10.2 when we checked. Its redis and valkey formulae can’t be installed together, because both install programs named redis-*.

From Homebrew’s formula (we read it rather than install it), on Apple silicon:

On an Intel Mac, replace /opt/homebrew with /usr/local. The formula edits the config so the server listens on 127.0.0.1 and ::1 only.

Find your connection details

Redis has 16 numbered databases by default (0 to 15), each with its own keys. Clients start in 0.

Docker: no password and no protected mode. On a fresh redis:8 container:

docker exec redis redis-cli CONFIG GET protected-mode
docker exec redis redis-cli ACL LIST

protected-mode
no
user default on nopass sanitize-payload ~* &* +@all

The server says so in its log:

# WARNING: Redis does not require authentication and is not protected by network restrictions. Redis will accept connections from any IP address on any network interface.

Protected mode, on by default since Redis 3.2, makes a server with no password answer only connections from the loopback interface. Connections through a published Docker port don’t arrive that way, so the image turns it off. Its documentation says that if you expose the port it’s open to anyone without a password, and recommends setting one.

Homebrew keeps Redis’s stock settings: protected-mode yes and no requirepass. Because the server listens on localhost only, protected mode doesn’t get in your way.

Set a password

requirepass gives the built-in default user a password. In Docker, pass it as an argument:

docker run --name redis -p 127.0.0.1:6379:6379 -d redis:8 redis-server --requirepass '<password>'

With Homebrew, add requirepass <password> to /opt/homebrew/etc/redis.conf and run brew services restart redis. Then a client without the password, and one with the wrong password, get (from redis-cli on a temporary redis:8 container):

NOAUTH Authentication required.

AUTH failed: WRONGPASS invalid username-password pair or user is disabled.

Add ACL users

Since Redis 6, you can also create named users, each with a password and its own permissions (ACL rules). Give them as --user arguments, as user lines in redis.conf, or with ACL SETUSER. This one can run everything except dangerous commands, on keys starting with app: only:

docker run --name redis -p 127.0.0.1:6379:6379 -d redis:8 \
  redis-server --requirepass '<password>' \
  --user app on '><app-password>' '~app:*' '+@all' '-@dangerous'

> followed by a password sets it, ~ gives a key pattern, +@all and -@dangerous add and remove command categories. Signed in as app, ACL WHOAMI answered app, and writing a key outside app:* was refused:

NOPERM No permissions to access a key

Use a config file

Docker’s documentation for the image mounts it at /usr/local/etc/redis/redis.conf:

docker run --name redis -p 127.0.0.1:6379:6379 -d \
  -v "$PWD/redis.conf":/usr/local/etc/redis/redis.conf \
  redis:8 redis-server /usr/local/etc/redis/redis.conf

If you start from Redis’s stock redis.conf, change two lines. Its bind 127.0.0.1 -::1 makes the server listen inside the container only, so the published port can’t reach it (use bind * -::*, which is what the image uses). And its protected-mode yes refuses outside connections until you set a password. See Troubleshooting for what each looks like.

Connection string

redis://localhost:6379/0
redis://:<password>@localhost:6379/0
redis://app:<app-password>@localhost:6379/0

The first has no password; the second is a requirepass password (nothing before the colon: the default user); the third is an ACL user. The number at the end is the database. See Redis connection strings and special characters in passwords.

TLS

Not needed for a server on your own Mac, and neither the image nor Homebrew sets up certificates. Both are built with TLS support, so you can try it with your own certificates:

redis-server --port 0 --tls-port 6379 \
  --tls-cert-file server.pem --tls-key-file server.key --tls-ca-cert-file ca.pem

--port 0 turns off the unencrypted port. By default Redis then also requires every client to present a certificate signed by that CA (mutual TLS); add --tls-auth-clients optional to make client certificates optional. Clients use rediss:// URLs or redis-cli --tls. Our TLS-only test server, a redis:8 container run this way, answered redis-cli -u rediss://… --cacert ca.pem PING with PONG.

Connect with Inlet

1. Choose New Connection, pick Redis, and enter localhost and port 6379. Or paste a redis:// URL and Inlet fills in the form.
2. Leave the user and password empty if you didn’t set a password. For requirepass, enter the password only; for an ACL user, its name and password. Save the password in the Keychain, or have Inlet ask every time.
3. Leave the database at 0 unless your app uses another number.
4. Tag the connection local.

The sidebar shows each database (db0, db1…) with the key namespaces in it, such as user:* and session:*, found from a sample of the keys, plus All keys.

Connect from the command line

The container has redis-cli, so you don’t need one on your Mac:

docker exec -it redis redis-cli

Homebrew’s redis puts redis-cli on your PATH:

redis-cli -h localhost -p 6379 PING

With a password, --askpass asks for it. -a <password> works too, but prints a warning, because other users of the machine can see command lines:

Warning: Using a password with '-a' or '-u' option on the command line interface may not be safe.

For an ACL user, put the password in REDISCLI_AUTH (no warning) and name the user:

REDISCLI_AUTH='<app-password>' redis-cli --user app

Troubleshooting

The messages below come from Redis 8.10.2 on temporary redis:8 containers, reached through a port published on the Mac (from redis-cli in a second container, or from the Mac itself).

• Connection refused: nothing is listening on that port. The container isn’t running or its port isn’t published, or the Homebrew service is stopped (brew services list shows it; its log is /opt/homebrew/var/log/redis.log).

  Could not connect to Redis at host.docker.internal:26399: Connection refused
  

  Inlet reports Couldn’t connect to localhost:6379: Connection refused.

• Error: Server closed the connection: the port is published but Redis inside the container listens on 127.0.0.1 only, usually from a stock redis.conf. Set bind * -::*.

• DENIED Redis is running in protected mode: protected mode is on (a config file turned it on), there’s no password, and your connection comes through the published port. The server’s reply lists four ways out; setting a password is the right one.

  -DENIED Redis is running in protected mode because protected mode is enabled and no password is set for the default user. In this mode connections are only accepted from the loopback interface. …
  

• NOAUTH Authentication required: the server has a password and your client didn’t send one. Inlet says The server needs a password. and asks for it in the connection window.

• WRONGPASS invalid username-password pair: wrong password, or the right password with the wrong user name. Inlet says Wrong user name or password.

• Another server already uses port 6379: Homebrew’s Redis, Valkey, or another container. Stop one, or publish a different host port, such as -p 127.0.0.1:6380:6379.

• Your keys are gone after docker rm: /data wasn’t a volume. Add -v redis-data:/data.