{"id":44780798,"url":"https://github.com/tigrisdata/tag-deploy","last_synced_at":"2026-02-16T07:37:05.698Z","repository":{"id":334512769,"uuid":"1141576862","full_name":"tigrisdata/tag-deploy","owner":"tigrisdata","description":"Tigris Acceleration Gateway deployment resources","archived":false,"fork":false,"pushed_at":"2026-02-04T07:03:06.000Z","size":28,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T07:33:32.390Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tigrisdata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-25T03:10:50.000Z","updated_at":"2026-02-03T19:02:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tigrisdata/tag-deploy","commit_stats":null,"previous_names":["tigrisdata/tag-deploy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tigrisdata/tag-deploy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigrisdata%2Ftag-deploy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigrisdata%2Ftag-deploy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigrisdata%2Ftag-deploy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigrisdata%2Ftag-deploy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tigrisdata","download_url":"https://codeload.github.com/tigrisdata/tag-deploy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigrisdata%2Ftag-deploy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29502934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T05:57:17.024Z","status":"ssl_error","status_checked_at":"2026-02-16T05:56:49.929Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-16T07:37:04.962Z","updated_at":"2026-02-16T07:37:05.691Z","avatar_url":"https://github.com/tigrisdata.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TAG Deployment Guide\n\nThis guide covers deploying TAG in various environments.\n\n## Prerequisites\n\n- Access to Tigris storage with API credentials\n\n## Docker\n\n### Quick Start\n\n```bash\n# Single node\ncd docker\ndocker-compose up -d\n\n# Cluster mode (3 TAG nodes with embedded cache)\ndocker-compose -f docker-compose-cluster.yml up -d\n```\n\n### Environment Variables\n\nCreate a `.env` file in the `docker/` directory:\n\n```bash\n# Required\nAWS_ACCESS_KEY_ID=your_access_key\nAWS_SECRET_ACCESS_KEY=your_secret_key\n\n# Optional\nTAG_LOG_LEVEL=info\n```\n\n### Single Node Setup\n\n```bash\n# Start service\ndocker-compose -f docker/docker-compose.yml up -d\n\n# View logs\ndocker-compose -f docker/docker-compose.yml logs -f tag\n\n# Stop service\ndocker-compose -f docker/docker-compose.yml down\n```\n\n### Cluster Setup\n\n```bash\n# Start 3 TAG nodes with embedded cache cluster\ndocker-compose -f docker/docker-compose-cluster.yml up -d\n\n# TAG endpoints are available at:\n# - http://localhost:8081 (tag-1)\n# - http://localhost:8082 (tag-2)\n# - http://localhost:8083 (tag-3)\n\n# Stop cluster\ndocker-compose -f docker/docker-compose-cluster.yml down -v\n```\n\n### Test\n\n```bash\n# Test with curl\ncurl -X GET http://localhost:8080/your-bucket/your-key \\\n  -H \"Authorization: AWS4-HMAC-SHA256 ...\"\n\n# Test with AWS CLI\naws s3 cp s3://your-bucket/your-key ./local-file \\\n  --endpoint-url http://localhost:8080\n```\n\n## Kubernetes\n\n### Prerequisites\n\n1. A running Kubernetes cluster\n2. kubectl configured to access the cluster\n\n### Deploy\n\n```bash\n# Create namespace (optional)\nkubectl create namespace tag\n\n# Create credentials secret\nkubectl create secret generic tag-credentials \\\n  --namespace tag \\\n  --from-literal=AWS_ACCESS_KEY_ID=your_key \\\n  --from-literal=AWS_SECRET_ACCESS_KEY=your_secret\n\n# Apply with kustomize\nkubectl apply -k kubernetes/base/ -n tag\n```\n\n### Kubernetes Manifests\n\nThe `kubernetes/base/` directory uses Kustomize format:\n\n| File | Description |\n|------|-------------|\n| `kustomization.yaml` | Kustomize configuration |\n| `statefulset.yaml` | TAG StatefulSet with embedded cache |\n| `service.yaml` | LoadBalancer Service for external access |\n| `service-headless.yaml` | Headless Service for cluster discovery |\n| `hpa.yaml` | Horizontal Pod Autoscaler |\n\n## Native\n\nRun TAG as a native process using pre-built binaries with embedded cache.\n\n### Quick Start\n\n```bash\n# Set credentials\nexport AWS_ACCESS_KEY_ID=your_access_key\nexport AWS_SECRET_ACCESS_KEY=your_secret_key\n\n# Start service\n./native/run.sh start\n\n# Check status\n./native/run.sh status\n\n# Stop service\n./native/run.sh stop\n```\n\n### Commands\n\n| Command | Description |\n|---------|-------------|\n| `start` | Download binary (if needed) and start TAG |\n| `stop` | Stop service |\n| `stop --clean` | Stop service and remove all data |\n| `status` | Show running status and health |\n| `logs [lines]` | Show logs (default: 50 lines) |\n| `help` | Show usage information |\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AWS_ACCESS_KEY_ID` | (required) | AWS access key |\n| `AWS_SECRET_ACCESS_KEY` | (required) | AWS secret key |\n| `TAG_VERSION` | `v1.5.1` | TAG version to download |\n| `TAG_LOG_LEVEL` | `info` | Log level: debug, info, warn, error |\n| `TAG_PORT` | `8080` | TAG HTTP port |\n| `TAG_CACHE_MAX_DISK_USAGE` | `107374182400` | Max cache disk usage in bytes (100GB) |\n| `BIN_DIR` | `native/.bin` | Binary download directory |\n| `DATA_DIR` | `/tmp/native-data` | Data directory for logs and cache |\n\n### Examples\n\n```bash\n# Start with debug logging\nTAG_LOG_LEVEL=debug ./native/run.sh start\n\n# Use specific version\nTAG_VERSION=v1.5.1 ./native/run.sh start\n\n# View logs\n./native/run.sh logs 100\n\n# Stop and clean all data\n./native/run.sh stop --clean\n```\n\n## Cache Configuration\n\nTAG uses an embedded distributed cache. Each TAG instance has its own local RocksDB-based cache storage.\n\n### Single Node\n\nFor single-node deployments, configure:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TAG_CACHE_NODE_ID` | auto | Unique node identifier |\n| `TAG_CACHE_DISK_PATH` | `/data/cache` | Cache data directory |\n| `TAG_CACHE_MAX_DISK_USAGE` | `0` (unlimited) | Max disk usage in bytes |\n\n### Cluster Mode\n\nFor clustered deployments, nodes communicate via:\n- **Port 7000**: Gossip port for cluster discovery\n- **Port 9000**: Port for cluster internal communication\n\nAdditional cluster configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TAG_CACHE_CLUSTER_ADDR` | `:7000` | Gossip protocol address |\n| `TAG_CACHE_GRPC_ADDR` | `:9000` | Cluster internal communication address |\n| `TAG_CACHE_ADVERTISE_ADDR` | (auto) | Address advertised to peers |\n| `TAG_CACHE_SEED_NODES` | (none) | Cluster discovery nodes |\n\n## Production Considerations\n\n### High Availability\n\n- Deploy multiple TAG replicas using the StatefulSet\n- Each TAG node has its own embedded cache storage\n- Use Kubernetes pod anti-affinity rules for node distribution\n- Configure health checks for automatic recovery\n\n### Scaling\n\n**Horizontal Scaling:**\n- TAG nodes form a distributed cache cluster\n- Adding nodes automatically rebalances cache keys\n- HPA can scale based on CPU/memory metrics\n- Note: Scaling down may temporarily reduce cache hit ratio\n\n**Vertical Scaling:**\n- Increase memory for high concurrent connection count\n- Increase CPU for high request throughput\n- SSD storage is required for cache performance\n\n### Health Checks\n\nTAG exposes a health endpoint:\n\n```\nGET /health\n```\n\nReturns `200 OK` when healthy.\n\n### Monitoring\n\n1. Expose `/metrics` endpoint for Prometheus scraping\n2. Set up alerts for:\n   - High error rate (`tag_requests_total{status=\"error\"}`)\n   - Low cache hit ratio (`tag_cache_hits_total / (tag_cache_hits_total + tag_cache_misses_total)`)\n   - High upstream latency (`tag_upstream_request_duration_seconds`)\n\n## Benchmarks\n\nSee [BENCHMARKS.md](BENCHMARKS.md) for performance results from go-ycsb testing on EC2.\n\n## Troubleshooting\n\n### Common Issues\n\n**No cache hits:**\n- Verify TAG is running with embedded cache enabled\n- Check TAG logs for cache initialization errors\n- Ensure disk path is writable\n\n**Authentication failures:**\n- Verify credentials are set correctly\n- Check clock sync between client and TAG\n- Review signature calculation logs at debug level\n\n**High latency:**\n- Check upstream endpoint latency\n- Monitor cache hit ratio\n- Review disk I/O performance\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```bash\nTAG_LOG_LEVEL=debug ./tag\n```\n\nOr in Kubernetes:\n\n```yaml\nenv:\n  - name: TAG_LOG_LEVEL\n    value: \"debug\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigrisdata%2Ftag-deploy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftigrisdata%2Ftag-deploy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigrisdata%2Ftag-deploy/lists"}