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

• 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 python@3.12 -- python --version

Node/JavaScript/TypeScript Applications

Core Principles

Prefer

bun

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:pass@host.docker.internal: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:pass@host.docker.internal: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

uv tool install <pkg>

uv tool install ruff

uv pip install -g <pkg>

uv pip install -g requests

bun install -g <pkg>

bun install -g typescript

bunx <cmd>

bunx prettier --write .

cd ~/code && git clone <url>

docker compose up -d

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/