Skip to main content
This guide will walk you through setting up Shipped and tracking your first package in under 5 minutes.

​
Installation

1

Start Shipped with Docker

Run the following command to start Shipped:
docker run -d \
  --name shipped \
  -p 3000:3000 \
  -v shipped-data:/data \
  --restart unless-stopped \
  nipakke/shipped:1
Shipped will be available at http://localhost:3000
2

Create the config directory

Create the configuration directory that will hold your package lists:
# Get a shell in the container
docker exec -it shipped sh

# Config directory is automatically created at /data/config
ls -la /data/config
Or, if using a bind mount:
mkdir -p /path-to-data/config
3

Add your first package list

Create a lists.yaml file in the config directory to define which packages to track:
# Using docker exec
docker exec -it shipped sh -c 'cat > /data/config/lists.yaml <<EOF
- name: My Packages
  description: Packages I use daily
  groups:
    - name: frontend
      displayName: Frontend Tools
      packages:
        - provider: github
          name: vuejs/vue
          displayName: Vue.js
        - provider: npm
          name: vue
EOF'
Or create the file directly if using a bind mount:
/path-to-data/config/lists.yaml
- name: My Packages
  description: Packages I use daily
  groups:
    - name: frontend
      displayName: Frontend Tools
      packages:
        - provider: github
          name: vuejs/vue
          displayName: Vue.js
        - provider: npm
          name: vue
4

View your tracked packages

Open http://localhost:3000 in your browser. You should see:
  • A list titled “My Packages” in the header navigation
  • The “Frontend Tools” group with Vue.js releases from both GitHub and NPM
  • Latest release versions with links to the official releases
Configuration changes are applied automatically - no restart needed!

​
Add More Packages

Edit your lists.yaml to track additional packages: 
- name: My Packages
  groups:
    - name: frontend
      displayName: Frontend Tools
      packages:
        - provider: github
          name: vuejs/vue
        - provider: npm
          name: vue
        - provider: npm
          name: react
        - provider: github
          name: facebook/react

    - name: backend
      displayName: Backend Services
      packages:
        - provider: docker
          name: postgres
          displayName: PostgreSQL
          extra:
            tags: ["latest", "alpine"]
        - provider: python
          name: fastapi

​
Customize Provider Settings

Create a providers.yaml file to configure provider-specific defaults:
/data/config/providers.yaml
github:
  extra:
    maxReleases: 5
    includePrereleases: false

npm:
  extra:
    tags:
      - latest
      - beta

docker:
  extra:
    tags:
      - latest
      - alpine
These settings apply to all packages from that provider unless overridden in lists.yaml.

​
Configure the UI

Create a ui.yaml file to customize the interface:
/data/config/ui.yaml
# Maximum lists to show in header navigation
maxListsInHeader: 3

​
Enable Real-Time Updates

Create a general.yaml file to enable config streaming:
/data/config/general.yaml
# Changes appear in the UI without page refresh
streamConfigChanges: true

​
Understanding Package Providers

Shipped supports multiple package providers with different naming formats:
ProviderName FormatExample
GitHubowner/repovuejs/vue
NPMpackage namevue, @types/react
Dockerimage or namespace/imagepostgres, library/nginx
Pythonpackage namedjango, fastapi

​
Smart Caching

Shipped automatically caches package data to minimize API calls:
  • L1 Memory Cache: Fast in-memory storage (default: 50MB, 2000 items)
  • L2 File Cache: Persistent storage in /data/cache (default: 3 hours TTL)
Cache settings can be configured via environment variables: 
-e SERVER_PACKAGES_CACHE_TTL=10800        # 3 hours in seconds
-e SERVER_PACKAGES_CACHE_MAX_SIZE=50mb
-e SERVER_PACKAGES_CACHE_MAX_ITEMS=2000

​
Troubleshooting

  • Check that lists.yaml is in the correct location (/data/config/lists.yaml)
  • Verify YAML syntax is valid (use a YAML validator)
  • Check Docker logs: docker logs shipped
  • Ensure package names use the correct format for each provider
  • Shipped watches config files automatically - no restart needed
  • If using network volumes, set SERVER_CONFIG_WATCH_POLLING=true
  • Check logs for file watching errors
  • GitHub: Set a GitHub token in providers.yaml for higher rate limits
  • Adjust cache TTL to reduce API calls
  • Reduce SERVER_PACKAGES_FETCH_CONCURRENCY from default 10

​
Next Steps

Configuration Files

Complete YAML configuration reference

Providers

Learn about all supported providers

Docker Compose

Production-ready Docker Compose setup

Environment Variables

Complete environment variable reference

Build docs developers (and LLMs) love

Get started for freeTalk to us