Installation

TagCache supports multiple installation methods across different platforms. Choose the method that best fits your environment.

Pre-built Binaries (Recommended)

Download the latest binaries from our GitHub Releases page.

macOS

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Download for Apple Silicon (ARM64)
curl -L -o tagcache-macos-arm64.tar.gz \
  https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache-macos-arm64.tar.gz

# Extract
tar xzf tagcache-macos-arm64.tar.gz

# Install globally
sudo cp tagcache bench_tcp /usr/local/bin/

# Verify installation
tagcache --version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Download for Intel (x86_64)
curl -L -o tagcache-macos-x86_64.tar.gz \
  https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache-macos-x86_64.tar.gz

# Extract
tar xzf tagcache-macos-x86_64.tar.gz

# Install globally
sudo cp tagcache bench_tcp /usr/local/bin/

# Verify installation
tagcache --version

Linux

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Download for Linux x86_64
curl -L -o tagcache-linux-x86_64.tar.gz \
  https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache-linux-x86_64.tar.gz

# Extract
tar xzf tagcache-linux-x86_64.tar.gz

# Install globally
sudo cp tagcache bench_tcp /usr/local/bin/

# Verify installation
tagcache --version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Download for Linux ARM64
curl -L -o tagcache-linux-arm64.tar.gz \
  https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache-linux-arm64.tar.gz

# Extract
tar xzf tagcache-linux-arm64.tar.gz

# Install globally
sudo cp tagcache bench_tcp /usr/local/bin/

# Verify installation
tagcache --version

Windows

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Download for Windows x86_64
Invoke-WebRequest -Uri "https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache-windows-x86_64.zip" -OutFile "tagcache-windows-x86_64.zip"

# Extract (Windows 10+)
Expand-Archive -Path "tagcache-windows-x86_64.zip" -DestinationPath "C:\tagcache"

# Add to PATH (optional)
$env:PATH += ";C:\tagcache"

# Verify installation
tagcache --version

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Download for Windows ARM64
Invoke-WebRequest -Uri "https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache-windows-arm64.zip" -OutFile "tagcache-windows-arm64.zip"

# Extract (Windows 10+)
Expand-Archive -Path "tagcache-windows-arm64.zip" -DestinationPath "C:\tagcache"

# Add to PATH (optional)
$env:PATH += ";C:\tagcache"

# Verify installation
tagcache --version

Package Managers

Homebrew (macOS/Linux)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Add the TagCache tap
brew tap aminshamim/tap

# Install TagCache
brew install tagcache

# Verify installation
tagcache --version

# Start service (optional)
brew services start tagcache

Debian/Ubuntu (APT)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
# Download the .deb package
curl -L -o tagcache.deb \
  https://github.com/aminshamim/tagcache/releases/download/v1.0.8/tagcache_1.0.8_amd64.deb

# Install
sudo dpkg -i tagcache.deb

# Fix dependencies if needed
sudo apt-get install -f

# Enable and start service
sudo systemctl enable tagcache
sudo systemctl start tagcache

# Check status
sudo systemctl status tagcache

Docker

Docker Run

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Basic run with default settings
docker run -d \
  --name tagcache \
  -p 1984:1984 \
  -p 8080:8080 \
  aminshamim/tagcache

# With custom configuration
docker run -d \
  --name tagcache \
  -p 1984:1984 \
  -p 8080:8080 \
  -v /path/to/your/tagcache.conf:/etc/tagcache/tagcache.conf:ro \
  aminshamim/tagcache

# With environment variables
docker run -d \
  --name tagcache \
  -p 1984:1984 \
  -p 8080:8080 \
  -e TAGCACHE_AUTH_USERNAME=myuser \
  -e TAGCACHE_AUTH_PASSWORD=mypassword \
  aminshamim/tagcache

Docker Compose

Create a docker-compose.yml file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
version: '3.8'

services:
  tagcache:
    image: aminshamim/tagcache:latest
    container_name: tagcache
    ports:
      - "1984:1984"  # TCP port
      - "8080:8080"  # HTTP port
    environment:
      - TAGCACHE_AUTH_USERNAME=admin
      - TAGCACHE_AUTH_PASSWORD=secure-password
    volumes:
      - ./tagcache.conf:/etc/tagcache/tagcache.conf:ro
      - tagcache_data:/var/lib/tagcache
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  tagcache_data:

Run with Docker Compose:

1
docker-compose up -d

Building from Source

Prerequisites

Rust 1.70 or later
Git

Build Steps

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# Clone the repository
git clone https://github.com/aminshamim/tagcache.git
cd tagcache

# Build release version
cargo build --release

# The binary will be available at
./target/release/tagcache

# Optionally, install globally
cargo install --path .

Build with UI Embedded

1
2
3
4
5
# Build with embedded web UI (default)
cargo build --release --features embed-ui

# Build without embedded UI (smaller binary)
cargo build --release --no-default-features

Cross-compilation

TagCache supports cross-compilation for different architectures:

1
2
3
4
5
6
7
# Install cross-compilation tool
cargo install cross

# Build for different targets
cross build --release --target x86_64-unknown-linux-gnu
cross build --release --target aarch64-unknown-linux-gnu
cross build --release --target x86_64-pc-windows-gnu

Verification

After installation, verify TagCache is working correctly:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
# Check version
tagcache --version

# Start server in background
tagcache server &

# Wait a moment for startup
sleep 2

# Test basic functionality
tagcache --username admin --password password put "test" "hello"
tagcache --username admin --password password get key "test"

# Stop the server
pkill tagcache

Next Steps

After successful installation:

Configuration

Configure TagCache for your environment

Getting Started

Learn basic usage and operations

Deployment

Production deployment guides

Troubleshooting

Common Issues

Permission Denied

1
2
# Make sure the binary is executable
chmod +x tagcache

Port Already in Use

1
2
3
4
5
6
# Check what's using the ports
lsof -i :8080
lsof -i :1984

# Kill processes if needed
sudo pkill -f tagcache

Configuration File Not Found

1
2
3
4
5
# Create default config directory
sudo mkdir -p /etc/tagcache

# Generate sample config
tagcache config generate > /etc/tagcache/tagcache.conf

Getting Help

Check the GitHub Issues
Review the Configuration Guide
Join our community discussions

For enterprise support or custom installations, please contact us through GitHub.

Getting Started Configuration