name: installing-apps-tools-and-services
description: "Use this skill when installing applications, packages, tools, or services on the system. Handles Python (uv), Node/JS/TS (bun), Docker containers, and GitHub-sourced installations with mise-managed tools and ecosystem integration patterns."

Installing Apps and Packages

Comprehensive guide for installing applications, packages, and services following Jarad's ecosystem patterns and tool preferences.

When to Use This Skill

Trigger this skill when:

• Installing Python applications or packages (CLI tools, libraries, services)
• Installing Node.js/JavaScript/TypeScript applications or packages
• Setting up containerized applications with Docker Compose
• Cloning and installing GitHub-sourced projects
• Integrating new tools into the existing ecosystem (proxy network, traefik, shared databases)
• Configuring applications to work with mise-managed tooling
• Setting up application secrets and environment variables

General Workflow

1. Gather Data on Install Target

Inspect Current Host:

# Check OS and architecture
uname -a
lsb_release -a
arch

# Check mise-managed tools
mise ls --current

# Check available databases/services
systemctl status postgresql redis neo4j qdrant

# Check Docker network
docker network ls | grep proxy

Key Information to Note:

• OS: Ubuntu/Debian-based Linux
• Architecture: x86_64
• Package managers: uv (Python), bun (Node), mise (version management)
• Native services: PostgreSQL, Redis
• Docker network: proxy (system-wide Traefik network)
• Domain conventions: *.delo.sh for services

2. Gather Data on Thing Being Installed

Use Official Channels:

• Check main GitHub repository (README, installation docs)
• Review official documentation site
• Examine release notes and installation guides
• Look for Docker Compose examples if applicable
• Check for .env.example or configuration templates

Critical Questions:

• What runtime does it require? (Python, Node, Rust, Go?)
• Is it a CLI tool, library, or service?
• Does it need a database? (Can we use native Postgres/Redis?)
• Does it expose HTTP endpoints? (Needs Traefik integration?)
• What secrets/API keys does it need? (Check ~/.config/zshyzsh/secrets.zsh)

3. Determine Installation Method

Decision Tree:

Is it available in the mise registry?
├─ Yes? → mise install <package> #easy peasy done!

Is it Python-based?
├─ CLI tool → uv tool install
├─ Library → uv pip install -g
└─ Service → Docker or uv pip install -g

Is it Node/JS/TS-based?
├─ CLI tool → bun install -g or bunx (one-offs)
├─ Library → bun add
└─ Service → Docker or native bun

Is it containerized?
└─ Follow Docker/Containerized Workflow

Is it from GitHub?
└─ Clone to ~/code and apply appropriate install method

Python Applications

Core Principles

ALWAYS use uv as the package tool

• Prefer global installs over venv
• Use mise-managed uv and python
• End goal: invoke as someApp, not uv run someApp
• Preferred bin path: ~/.local/bin

Installation Patterns

CLI Tools:

# Use uv tool install for CLI tools
uv tool install <package-name>

# Verify installation
which <tool-name>
<tool-name> --version

Example - Installing ruff:

# Install globally as CLI tool
uv tool install ruff

# Verify
ruff --version

Libraries/Packages:

# Use uv sync first if pyproject allows
uv sync

# Use global install instead of pip install
uv pip install -g <package-name>

# If docs say "pip install -r requirements.txt", translate to:
uv pip install -r requirements.txt

Services (Python-based):

For services like FastAPI apps, Agno agents, etc.:

# Clone to ~/code if from GitHub
cd ~/code
gh repo clone <repo-url>
cd <project-name>

# Install dependencies globally or in project
uv sync

# Or use project-specific environment
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

Tool Replacements

Replace these commands:

• pip install → uv pip install -g
• pipx install → uv tool install
• python -m venv → uv venv (if venv needed)

Mise Integration

Ensure mise manages Python and uv:

# Check current versions
mise ls --current

# Install/update if needed
mise use python@latest uv@latest -g

# Verify
which python
which uv

# Explicitly invoke
mise x -- uv --version
mise x [email protected] -- python --version

Node/JavaScript/TypeScript Applications

Core Principles

Prefer bun over npm

• Use mise-managed bun/nodejs
• Use globally installed tools
• Use latest bun/nodejs versions
• OK to use npx or bunx for one-off commands

Installation Patterns

CLI Tools:

# Global installation with bun
bun install -g <package-name>

# Verify
which <tool-name>
<tool-name> --version

Example - Installing typescript:

# Install globally
bun install -g typescript

# Verify
tsc --version

One-off Commands:

# Use bunx for one-time executions
bunx create-react-app my-app
bunx prettier --write .

Project Dependencies:

# For project-specific packages
cd ~/code/<project-name>
bun install
bun add <package-name>

Mise Integration

Ensure mise manages bun/node:

# Install/update globally
mise use bun@latest -g
mise use node@latest -g

# Verify
which bun
which node
bun --version
node --version

GitHub-Sourced Installations

Core Principle

Always clone into ~/code

Workflow

# 1. Clone to standard location
cd ~/code
git clone <repo-url>
cd <project-name>

# 2. Initialize with iMi (optional, if it's a project you'll develop)
imi init

# 3. Apply appropriate installation method based on type
# - Python: uv pip install -g -r requirements.txt
# - Node: bun install
# - Rust: cargo install --path .
# - Go: go install

Example - Installing a Python CLI from GitHub:

cd ~/code
git clone https://github.com/user/awesome-tool
cd awesome-tool

# Install as tool
uv tool install .

# Or if it has requirements
uv pip install -g -r requirements.txt
uv pip install -g .

Docker/Containerized Installations

Core Principles

Ecosystem Integration:

1. Modify compose files to fit Docker container ecosystem
2. Avoid common port conflicts (3000, 8080, etc.)
3. Use system-wide proxy network for Traefik integration
4. Connect to native services (Postgres, Redis, Neo4j, Qdrant)
5. Use simple, common-sense subdomains (*.delo.sh)

Workflow

1. Examine and Modify Compose File

Critical Modifications:

# docker-compose.yml

services:
  app:
    image: awesome-app:latest
    container_name: awesome-app # Simple slug, no numbers/postfixes
    restart: unless-stopped
    networks:
      - proxy # System-wide network
    environment:
      # Use native databases
      - DATABASE_URL=postgresql://user:[email protected]:5432/dbname
      - REDIS_URL=redis://host.docker.internal:6379
      - QDRANT_URL=http://host.docker.internal:6333
    labels:
      # Traefik configuration
      - "traefik.enable=true"
      - "traefik.http.routers.awesome-app.rule=Host(`awesome.delo.sh`)"
      - "traefik.http.routers.awesome-app.entrypoints=websecure"
      - "traefik.http.routers.awesome-app.tls.certresolver=letsencrypt"
      - "traefik.http.services.awesome-app.loadbalancer.server.port=8000"

networks:
  proxy:
    external: true

Port Management:

• Avoid exposing ports directly unless necessary
• Use Traefik labels for HTTP/HTTPS access
• If port exposure needed, choose random non-privileged port (e.g., 8473, 9234)
• Never use common ports: 3000, 8000, 8080, 5000, etc.

Database Integration:

# DON'T add separate database services
services:
  postgres:  # ❌ Don't do this
    image: postgres:16
    ...

# DO connect to native instances
environment:
  # ✅ Use host.docker.internal
  - DATABASE_URL=postgresql://user:[email protected]:5432/dbname
  - REDIS_URL=redis://host.docker.internal:6379

2. Create .env File

Resolve Secrets:

1. Check provided .env.example or README
2. Cross-reference with system secrets: ~/.config/zshyzsh/secrets.zsh
3. Generate new secrets if needed (API keys, passwords, etc.)

# Example .env file
DATABASE_URL=postgresql://delorenj:${POSTGRES_PASSWORD}@host.docker.internal:5432/awesome_app
REDIS_URL=redis://host.docker.internal:6379
SECRET_KEY=${AWESOME_APP_SECRET_KEY}  # From secrets.zsh
API_KEY=${OPENAI_API_KEY}  # From secrets.zsh

Common Secret Locations:

• OpenAI: $OPENAI_API_KEY
• Anthropic: $ANTHROPIC_API_KEY
• GitHub: $GITHUB_TOKEN
• Database: $POSTGRES_PASSWORD

3. Build and Deploy

# Production build preferred
docker compose build --no-cache

# Deploy with proper restart policy
docker compose up -d

# Verify
docker compose ps
docker compose logs -f

Container Naming:

• Use simple slugs: awesome-app, not awesome-app-1 or awesome-app_container
• Set container_name explicitly in compose file
• Restart policy: unless-stopped is usually sufficient

Lock Down Configuration:

For production deployments, create custom image and push to Docker Hub:

# Build custom image
docker build -t delorenj/awesome-app:latest .

# Push to Docker Hub
docker push delorenj/awesome-app:latest

# Update compose to use locked image
services:
  app:
    image: delorenj/awesome-app:latest

Traefik Integration Patterns

Basic HTTP Service:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.app.rule=Host(`app.delo.sh`)"
  - "traefik.http.routers.app.entrypoints=websecure"
  - "traefik.http.routers.app.tls.certresolver=letsencrypt"

Service with Path Prefix:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.app.rule=Host(`delo.sh`) && PathPrefix(`/app`)"
  - "traefik.http.middlewares.app-strip.stripprefix.prefixes=/app"
  - "traefik.http.routers.app.middlewares=app-strip"

WebSocket Support:

labels:
  - "traefik.http.routers.app.rule=Host(`ws.delo.sh`)"
  - "traefik.http.services.app.loadbalancer.server.port=8080"

Database Setup

Create Database (if needed):

# Connect to native Postgres
psql -U delorenj -d postgres

# Create database
CREATE DATABASE awesome_app;

# Create user if needed
CREATE USER awesome_app WITH PASSWORD 'secure_password';
GRANT ALL PRIVILEGES ON DATABASE awesome_app TO awesome_app;

Initialize Schema:

# If app has migrations
docker compose exec app python manage.py migrate

# Or run SQL files
psql -U delorenj -d awesome_app -f schema.sql

Post-Installation Verification

Check Tool Availability

# For CLI tools
which <tool-name>
<tool-name> --version

# For Python packages
python -c "import <package>"

# For Node packages
node -e "require('<package>')"

# For Docker services
docker compose ps
curl http://localhost:<port>/health
curl https://app.delo.sh/health

Verify Mise Integration

# List all mise-managed tools
mise ls --current

# Verify PATH includes mise bins
echo $PATH | grep mise

Verify Service Integration

# Test database connection
psql -U delorenj -d awesome_app -c "SELECT 1"

# Test Redis connection
redis-cli ping

# Test Traefik routing
curl -I https://app.delo.sh

Common Patterns

Pattern: Installing Python MCP Server

# 1. Clone to ~/code
cd ~/code
git clone https://github.com/user/mcp-server
cd mcp-server

# 2. Install globally
uv pip install -g .

# 3. Verify
which mcp-server
mcp-server --version

# 4. Configure in Claude Code
# Add to claude_desktop_config.json

Pattern: Installing Node CLI Tool

# 1. Install globally with bun
bun install -g awesome-cli

# 2. Verify
which awesome-cli
awesome-cli --version

# 3. Add to mise if version pinning needed
mise use awesome-cli@latest -g

Pattern: Docker Service with Native Database

# 1. Create project structure
cd ~/docker/trunk-main/stacks/ai
mkdir awesome-service
cd awesome-service

# 2. Create compose file
cat > docker-compose.yml << 'EOF'
services:
  awesome:
    image: awesome/service:latest
    container_name: awesome-service
    restart: unless-stopped
    networks:
      - proxy
    environment:
      - DATABASE_URL=postgresql://delorenj:${POSTGRES_PASSWORD}@host.docker.internal:5432/awesome
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.awesome.rule=Host(`awesome.delo.sh`)"
      - "traefik.http.routers.awesome.entrypoints=websecure"
      - "traefik.http.routers.awesome.tls.certresolver=letsencrypt"

networks:
  proxy:
    external: true
EOF

# 3. Create .env from secrets
cat > .env << 'EOF'
POSTGRES_PASSWORD=<from secrets.zsh>
OPENAI_API_KEY=<from secrets.zsh>
EOF

# 4. Create database
psql -U delorenj -d postgres -c "CREATE DATABASE awesome"

# 5. Deploy
docker compose up -d

# 6. Verify
docker compose logs -f
curl https://awesome.delo.sh/health

Troubleshooting

Tool Not Found After Installation

# Check if installed
uv tool list
bun pm ls -g

# Check PATH
echo $PATH | grep -E '(\.local/bin|mise)'

# Verify mise activation
mise doctor

# Reinstall if needed
uv tool uninstall <tool>
uv tool install <tool>

Docker Service Won't Start

# Check logs
docker compose logs

# Verify network exists
docker network ls | grep proxy

# Test database connectivity
docker compose exec app psql $DATABASE_URL -c "SELECT 1"

# Check port conflicts
ss -tulpn | grep :<port>

Traefik Routing Issues

# Check Traefik dashboard
# (Access via configured dashboard URL)

# Verify labels are applied
docker inspect <container> | grep traefik

# Test DNS resolution
nslookup app.delo.sh

# Check certificate
curl -I https://app.delo.sh

Quick Reference

Installation Commands by Type

Key File Locations

• Secrets: ~/.config/zshyzsh/secrets.zsh
• Docker stacks: ~/docker/trunk-main/stacks/
• Code repos: ~/code/
• Mise config: ~/.config/mise/config.toml
• Local bins: ~/.local/bin/

Essential Checks

# Before installing
mise ls --current
which python uv bun node
docker network ls | grep proxy

# After installing
which <tool>
<tool> --version
mise doctor

# For Docker services
docker compose ps
docker compose logs
curl https://app.delo.sh/health

Resources

references/

• docker-compose-patterns.md - Common Docker Compose configurations
• traefik-labels-reference.md - Traefik label patterns
• native-service-connection.md - Connecting to native Postgres/Redis/Qdrant

scripts/

• install-python-cli.sh - Template for Python CLI installation
• install-node-cli.sh - Template for Node CLI installation
• setup-docker-service.sh - Template for Docker service setup

assets/

• docker-compose.template.yml - Standard compose file template
• .env.template - Standard .env template
• traefik-labels.yml - Common Traefik label configurations

See Also

• ecosystem-patterns skill - Overall ecosystem architecture and conventions
• mise-task-managing skill - Managing mise tasks and tool versions
• Docker Compose patterns in ecosystem-patterns/references/