Quickstart

Get TAG running in under 5 minutes. TAG caches your Tigris objects on local disk so repeated reads are served in microseconds instead of milliseconds — and you don't need to change any application code.

Prerequisites

You need a pair of Tigris credentials (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) with read-only access to all buckets in your Tigris organization. These are TAG's service credentials. Your application clients authenticate separately with their own credentials.

Install and run

Native Binary

# Download and install TAG
curl -sSL https://raw.githubusercontent.com/tigrisdata/tag-deploy/main/native/install.sh | bash

# Set your Tigris credentials
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>

# Start TAG
tag --config /etc/tag/config.yaml

The install script auto-detects your OS (Linux/macOS) and architecture (amd64/arm64) and places the binary in /usr/local/bin.

Docker

git clone https://github.com/tigrisdata/tag-deploy.git
cd tag-deploy

# Create docker/.env with credentials
cat > docker/.env <<EOF
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
EOF

# Start TAG
cd docker && docker compose up -d

The Docker image (tigrisdata/tag) uses Alpine Linux, runs as a non-root user, and persists cache data in a named volume.

For cluster mode and more options, see the Docker guide.

Kubernetes

git clone https://github.com/tigrisdata/tag-deploy.git
cd tag-deploy

kubectl create namespace tag

kubectl create secret generic tag-credentials \
  --namespace tag \
  --from-literal=AWS_ACCESS_KEY_ID=your_access_key \
  --from-literal=AWS_SECRET_ACCESS_KEY=your_secret_key

kubectl apply -k kubernetes/base/ -n tag

This deploys a 3-replica StatefulSet with embedded caching, gossip-based cluster discovery, and a LoadBalancer service on port 8080.

For production considerations and scaling, see the Kubernetes guide.

Verify it works

TAG is now listening on http://localhost:8080. Try a few requests to make sure everything is connected:

# Health check
curl http://localhost:8080/health

# List buckets
aws s3 ls --endpoint-url http://localhost:8080

# Download an object
aws s3 cp s3://my-bucket/my-key ./local-file --endpoint-url http://localhost:8080

Connect your application

TAG works with any S3 client. Just change your endpoint URL to point at TAG and make sure path-style addressing is enabled — that's it.

Path-Style Addressing Only

TAG supports path-style addressing (http://host:port/bucket/key). Virtual-hosted style (http://bucket.host:port/key) is not supported. Ensure your S3 client is configured for path-style access.

For client examples covering AWS CLI, Python boto3, streaming large files, and troubleshooting, see S3 Client Usage.

Troubleshooting

If something isn't working — TAG won't start, you're getting 403s, or every response shows X-Cache: MISS — see Troubleshooting in the Deployment Guide.