installing-apps-tools-and-services

What this skill does

# 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:**

```bash
# 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:**

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

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

**Example - Installing ruff:**

```bash
# Install globally as CLI tool
uv tool install ruff

# Verify
ruff --version
```

**Libraries/Packages:**

```bash
# 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.:

```bash
# 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:**

```bash
# 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:**

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

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

**Example - Installing typescript:**

```bash
# Install globally
bun install -g typescript

# Verify
tsc --version
```

**One-off Commands:**

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

**Project Dependencies:**

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

### Mise Integration

**Ensure mise manages bun/node:**

```bash
# 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

```bash
# 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:**

```bash
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:**

```yaml
# 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:**

```yaml
# 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.)

```bash
# Examp