dynamicalsystem.com / tinsnip
homelab infrastructure services
fork atom
tinsnip / NAMESPACE_CONFIGURATION.md
at fix-docker-install 3.8 kB view raw view code
dynamicalsystem.com revise symlinks, volumes and env maangement.
6e25a72f

Namespace Configuration#

The machine setup supports configurable namespaces for multi-tenant or multi-organization deployments.

How Namespace Numbers Work#

Each namespace is automatically assigned a number (1-9) used in the UID scheme:

  • The number is calculated from the namespace name using a deterministic hash
  • Same namespace always gets the same number across all deployments
  • No central registry or coordination needed
  • Supports up to 9 different namespaces

Examples:

  • dynamicalsystem → 1 (backward compatible with existing deployments)
  • mycompany → 7
  • acmecorp → 3

This number becomes the "N" in the TNSEP UID scheme, ensuring each namespace gets unique UIDs.

Namespace Detection Order#

The namespace is determined in this priority order:

  1. Environment variable: TIN_NAMESPACE=mycompany
  2. System file: /etc/tinsnip-namespace (created by tinsnip setup)
  3. Default: dynamicalsystem

Setting the Namespace#

Option 1: Environment Variable#

export TIN_NAMESPACE=mycompany
./machine/setup.sh tinsnip test DS412plus

Option 2: System-wide Configuration#

# Set namespace system-wide (requires sudo)
echo "mycompany" | sudo tee /etc/tinsnip-namespace
./machine/setup.sh tinsnip test DS412plus

Option 3: Per-command#

TIN_NAMESPACE=mycompany ./machine/setup.sh tinsnip test DS412plus

Impact of Namespace Configuration#

When namespace is set to mycompany, the deployment uses:

NFS Paths:

  • /volume1/mycompany/tinsnip/prod
  • /volume1/mycompany/tinsnip/test
  • /volume1/mycompany/gazette/prod
  • /volume1/mycompany/gazette/test

XDG Integration:

  • ~/.local/state/mycompany/@tinsnip
  • ~/.local/share/mycompany/@tinsnip
  • ~/.config/mycompany/@tinsnip

UID Convention: Dynamically calculated based on namespace

  • dynamicalsystem: 11000, 11010, etc. (N=1)
  • mycompany: 17000, 17010, etc. (N=7)
  • Each namespace gets unique UIDs to prevent conflicts

Port Allocation: Follows UID-based allocation

  • dynamicalsystem: 11000+, 11010+, etc.
  • mycompany: 17000+, 17010+, etc.

NAS Setup for Custom Namespace#

When using a custom namespace, create the corresponding directory structure on your NAS:

# On Synology NAS
ssh admin@DS412plus
sudo mkdir -p /volume1/mycompany/{tinsnip,gazette}/{prod,test}
# For mycompany namespace (N=7)
sudo chown 17000:17000 /volume1/mycompany/tinsnip/prod
sudo chown 17010:17010 /volume1/mycompany/tinsnip/test
sudo chown 17100:17100 /volume1/mycompany/gazette/prod
sudo chown 17110:17110 /volume1/mycompany/gazette/test
# ... etc

# Update /etc/exports
sudo vi /etc/exports
# Replace dynamicalsystem with mycompany in export paths:
/volume1/mycompany/tinsnip/prod	host(rw,async,no_subtree_check,all_squash,anonuid=17000,anongid=17000)
/volume1/mycompany/tinsnip/test	host(rw,async,no_subtree_check,all_squash,anonuid=17010,anongid=17010)

sudo exportfs -ra

Multi-Namespace Deployments#

You can run multiple namespaces on the same infrastructure:

# Company A
TIN_NAMESPACE=companya ./machine/setup.sh tinsnip prod DS412plus

# Company B  
TIN_NAMESPACE=companyb ./machine/setup.sh tinsnip prod DS412plus

Each namespace gets completely isolated:

  • Storage: Separate NFS directories
  • Users: Different UIDs based on namespace number
  • Services: Different ports based on UIDs
  • Processes: Complete isolation between namespaces

Important: The system supports up to 9 namespaces due to the single-digit constraint in the UID scheme. If you need more than 9 namespaces, you'll need separate infrastructure.

Testing Namespace Configuration#

# Test with custom namespace
TIN_NAMESPACE=testorg ./machine/test_functions.sh

# Test dry run with custom namespace
TIN_NAMESPACE=testorg ./machine/dry_run_test.sh