Getting started

This page takes you from the AWS Marketplace listing to a working cache: subscribe, launch the instance, connect to it, and store and read your first key.

You need: an AWS account with permission to subscribe to AWS Marketplace products, launch EC2 instances and use AWS Systems Manager.

1. Subscribe

Open the Valkey listing in AWS Marketplace, choose View purchase options, review the terms and subscribe. When the subscription is confirmed, choose Launch your software.

2. Launch the instance

On the EC2 launch page:

1. Keep the instance type at t3.medium, or choose one with at least 4 GiB of memory.
2. Under Configure storage, use an encrypted gp3 root volume of at least 16 GiB.
3. Under Network settings, allow no inbound traffic. The cache listens only on the instance itself, and Session Manager does not need an open port. If you also want SSH, allow port 22 from your administrative address range only.
4. Under Advanced details, choose an IAM instance profile that includes the AWS managed policy AmazonSSMManagedInstanceCore, so you can connect with Session Manager.
5. Choose Launch instance.

Session Manager needs outbound HTTPS

The instance reaches Systems Manager over outbound HTTPS. Keep the default outbound rule, or provide VPC endpoints for Systems Manager.

3. Connect

In the EC2 console, select the instance, choose Connect, then Session Manager, then Connect. Switch to the ubuntu user:

sudo -iu ubuntu

4. Wait for first boot

On first boot the instance creates its TLS certificates, the cache password and the access control list, then starts Valkey. Wait for it to finish:

cloud-init status --wait
systemctl is-active sushi-valkey-firstboot valkey

Both services report active when the cache is ready.

5. Run the walkthrough

The image includes a short script that checks the service, stores and reads a key, and confirms that a connection without a password is refused:

bash /opt/sushi/docs/demo.sh

6. Store and read a key

Use the helper client as root. It reads the password file for you:

sudo /opt/sushi/bin/valkey-cache-cli PING
sudo /opt/sushi/bin/valkey-cache-cli SET cache:session:demo 'user=pilot;cart=2'
sudo /opt/sushi/bin/valkey-cache-cli GET cache:session:demo

PING returns PONG, and GET returns the value you stored. Every key must start with cache:; other keys are refused.

Connect your application

Run your application on the same instance, or see Reach the cache from your VPC. Your client needs:

Setting	Value
Address	127.0.0.1, port 6379, TLS on (rediss://)
CA certificate	/usr/local/share/sushi/valkey/ca.pem
User name	cache
Password	the contents of /etc/valkey/credentials/cache.password
Key names	must start with cache:

The password file is readable by root only. Give it to your application through your own secret store, and keep it out of tickets, chat and screen recordings.

To use valkey-cli directly, pass the password through the VALKEYCLI_AUTH environment variable rather than on the command line:

sudo bash -c 'VALKEYCLI_AUTH=$(tr -d "\n" < /etc/valkey/credentials/cache.password) \
  valkey-cli --tls --cacert /usr/local/share/sushi/valkey/ca.pem \
  -h 127.0.0.1 -p 6379 --user cache --no-auth-warning PING'

Next, read Configuration to change the memory cap, open the cache to your VPC or rotate the password.