valknar/home
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
509dff728b84ce0937c3be1a2fbcbeb02ce57730
home/Projects/kompose/docs/content/5.stacks/link.md

16 KiB
Executable File
Raw Blame History

title, description, navigation
title description navigation
Link - Your Digital Memory Palace Bookmark everything, forget nothing!
icon
i-lucide-link

"Bookmark everything, forget nothing!" - Linkwarden

What's This All About?

Linkwarden is your self-hosted bookmark manager that doesn't just save links - it preserves entire web pages! Think of it as your personal Internet Archive. Every bookmark gets a screenshot, a PDF backup, and full-text search. Lost content, website changes, or dead links? Not your problem anymore!

The Archive Keeper

:icon{name="lucide:bookmark"} Linkwarden

Container: link_app
Image: ghcr.io/linkwarden/linkwarden:latest
Home: https://link.localhost
Database: PostgreSQL

Linkwarden is your digital librarian with superpowers:

  • :icon{name="lucide:camera"} Automatic Screenshots: Visual preview of every link
  • :icon{name="lucide:file-text"} Full Page Archives: Complete webpage backups (PDF & HTML)
  • :icon{name="lucide:search"} Full-Text Search: Find anything across all your bookmarks
  • :icon{name="lucide:tags"} Smart Organization: Tags, collections, and folders
  • :icon{name="lucide:users"} Team Collaboration: Share collections with others
  • :icon{name="lucide:globe"} Browser Extension: Save from anywhere (Chrome, Firefox, Edge)
  • :icon{name="lucide:smartphone"} Mobile Apps: iOS & Android (via PWA)
  • :icon{name="lucide:shield"} Privacy First: Your bookmarks stay on your server
  • :icon{name="lucide:zap"} Lightning Fast: Instant search across thousands of bookmarks

:icon{name="lucide:database"} PostgreSQL Database

Container: link_db
Image: postgres:16-alpine
Port: 5432 (internal only)

The PostgreSQL database stores:

  • Bookmark metadata and URLs
  • Tags and collections
  • User accounts and permissions
  • Search indices for lightning-fast queries

Configuration Breakdown

Database Persistence

volumes:
  - link_db_data:/var/lib/postgresql/data

All your bookmarks, tags, and archives are stored here. This is your treasure chest!

Application Data

volumes:
  - link_data:/data/data

This volume contains:

  • Screenshot images
  • PDF archives
  • Full webpage HTML backups
  • Uploaded file attachments

Environment Variables

Database Connection:

DATABASE_URL=postgresql://linkwarden:password@link_db:5432/linkwarden
POSTGRES_PASSWORD=your-secure-password-here

🔒 Change the default password before deploying!

Application Settings:

NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=https://link.localhost

Generate a secure secret with:

openssl rand -base64 32

Archive Configuration:

# Storage location
STORAGE_FOLDER=/data/data

# Archive options (all enabled by default)
ARCHIVE_ENABLED=true
SCREENSHOT_ENABLED=true
PDF_ENABLED=true

Why Linkwarden vs Browser Bookmarks?

Feature Linkwarden Browser Bookmarks
Archives ✅ Screenshots + PDFs ❌ Just URLs
Search ✅ Full-text in pages ❌ Title only
Sync ✅ All devices/browsers ⚠️ Single browser
Organization ✅ Tags + Collections ⚠️ Folders only
Sharing ✅ Team collaboration ❌ Export/import only
Dead Links ✅ Archived content ❌ Lost forever
Privacy ✅ Your server ⚠️ Browser syncs

First Time Setup :icon

1. Start the Stack

docker compose up -d

2. Create Your Account

URL: https://link.localhost
Click: "Sign Up"
Username: your-username
Email: your@email.com
Password: Something strong!

3. Configure Settings

After logging in:

  1. Settings → General
  2. Set your preferences:
    • Default view (Grid/List)
    • Archive options
    • Screenshot quality
    • PDF generation

4. Install Browser Extension

Chrome/Edge:

  • Visit Chrome Web Store
  • Search "Linkwarden"
  • Install extension
  • Configure server URL: https://link.localhost
  • Enter your credentials

Firefox:

  • Visit Firefox Add-ons
  • Search "Linkwarden"
  • Install extension
  • Configure server URL: https://link.localhost
  • Enter your credentials

5. Mobile Access (PWA)

  1. Visit https://link.localhost on mobile
  2. Browser menu → "Add to Home Screen"
  3. Now it works like a native app!

Using Linkwarden :icon

Adding Bookmarks

Via Browser Extension:

  1. Browse to any webpage
  2. Click Linkwarden extension icon
  3. Optionally add:
    • Tags (press Enter after each)
    • Collection
    • Description
  4. Click "Save"
  5. Done! Screenshots and archives generated automatically

Via Web Interface:

  1. Click "+ New Link"
  2. Paste URL
  3. Add tags and description
  4. Choose collection
  5. Save

Via Bookmarklet: Add this to your bookmarks bar:

javascript:(function(){window.open('https://link.localhost/new?url='+encodeURIComponent(window.location.href)+'&title='+encodeURIComponent(document.title));})();

Organizing with Collections

Create Collections:

  1. Sidebar → Collections → New
  2. Name it (e.g., "Work Resources", "Recipes", "Travel")
  3. Choose icon and color
  4. Add description

Use Cases:

  • 📚 Research topics
  • 🍳 Recipe collections
  • 💼 Work projects
  • 🎨 Design inspiration
  • 🛠️ Dev resources
  • ✈️ Travel planning

Smart Tagging

Best Practices:

  • Use lowercase (auto-converted)
  • Be consistent: javascript not JavaScript or JS
  • Use multi-word tags: web-development, machine-learning
  • Tag by topic, type, and project
  • Example: tutorial, react, project-alpha

Auto-Suggest: Start typing - existing tags appear!

Powerful Search :icon

Search works across:

  • Link titles
  • Descriptions
  • Tags
  • Full text of archived pages
  • URL content

Search Tips:

  • Use quotes for exact phrases: "kubernetes deployment"
  • Search by tag: tag:tutorial
  • Search by collection: collection:work
  • Combine: docker tag:tutorial collection:devops

Advanced Features

Bulk Actions

Select multiple links to:

  • Add/remove tags
  • Move to different collection
  • Delete
  • Export

Import Bookmarks

Import from:

  • Chrome/Firefox HTML exports
  • Pocket
  • Raindrop.io
  • Plain URL lists

Import Process:

  1. Settings → Import
  2. Choose format
  3. Upload file
  4. Map to collections
  5. Import!

Public Collections

Share collections publicly:

  1. Collection settings → Make Public
  2. Get shareable link
  3. Others can view (no account needed)
  4. Optional: Allow others to contribute

RSS Feed

Each collection has an RSS feed:

https://link.localhost/api/collections/[id]/feed

Use with RSS readers like Miniflux!

Archive Features :icon

Screenshot Archives

  • Captured on bookmark save
  • Full page screenshot (scrolls entire page)
  • Saved as PNG
  • Viewable in-app
  • Click to enlarge

PDF Archives

  • Complete webpage as PDF
  • Preserves formatting
  • Text-selectable
  • Downloadable
  • Great for offline reading

HTML Archives

  • Complete webpage saved
  • All assets included
  • Readable even if original dies
  • Full-text searchable

Re-Archive

If page content changes:

  1. Open bookmark
  2. Click "Re-archive"
  3. New snapshot created
  4. Old versions preserved

Collaboration Features :icon

Team Workspaces

  1. Create collection
  2. Settings → Members
  3. Invite by email/username
  4. Set permissions:
    • View only
    • Can contribute
    • Can edit
    • Admin

Activity Feed

See what your team is doing:

  • New bookmarks added
  • Tags updated
  • Collections modified
  • Member activity

Shared Collections

Perfect for:

  • Research teams
  • Project resources
  • Knowledge bases
  • Curated lists
  • Team documentation

API Access :icon

Linkwarden has a full REST API!

Get API Token:

  1. Settings → API
  2. Generate new token
  3. Copy and save securely

Example: Add Bookmark:

curl -X POST https://link.localhost/api/v1/links \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "name": "Example Site",
    "description": "An example bookmark",
    "tags": ["example", "test"],
    "collectionId": 1
  }'

Example: Search:

curl https://link.localhost/api/v1/links?q=docker \
  -H "Authorization: Bearer YOUR_TOKEN"

Automate Everything:

  • Save from scripts
  • Backup tools
  • CI/CD pipelines
  • Custom integrations

Browser Extension Tips :icon

Keyboard Shortcuts

Set in browser extension settings:

  • Default: Alt+Shift+L to save current page
  • Customize to your preference

Context Menu

Right-click on links:

  • "Save to Linkwarden"
  • Quick save without opening extension

Bulk Save

On pages with many links:

  1. Open extension
  2. Click "Save all links"
  3. Scans page for links
  4. Batch save selected links

Maintenance & Backups

Backup Strategy

# Backup PostgreSQL database
docker exec link_db pg_dump -U linkwarden linkwarden > backup.sql

# Backup archives and screenshots
tar -czf linkwarden-data-$(date +%Y%m%d).tar.gz ./link_data/

# Backup both (recommended)
docker compose exec link_db pg_dump -U linkwarden linkwarden | \
  gzip > backup-$(date +%Y%m%d).sql.gz

Restore from Backup

# Stop the stack
docker compose down

# Restore database
gunzip -c backup-20240101.sql.gz | \
  docker compose exec -T link_db psql -U linkwarden linkwarden

# Restore files
tar -xzf linkwarden-data-20240101.tar.gz

# Start stack
docker compose up -d

Database Maintenance

# Check database size
docker exec link_db psql -U linkwarden linkwarden -c \
  "SELECT pg_size_pretty(pg_database_size('linkwarden'));"

# Vacuum database (optimize)
docker exec link_db psql -U linkwarden linkwarden -c "VACUUM ANALYZE;"

Clean Old Archives

Over time, archives can grow large:

  1. Settings → Storage
  2. View storage usage
  3. Delete archives for links you don't need
  4. Or increase disk space allocation

Performance Tuning

Archive Settings

If storage/performance is a concern:

Reduce Screenshot Quality:

SCREENSHOT_QUALITY=medium  # high, medium, low

Disable Certain Archives:

PDF_ENABLED=false  # If you only need screenshots

Archive on Demand: Instead of auto-archiving, archive manually when needed

Database Optimization

# Increase shared memory (in docker-compose.yml)
services:
  link_db:
    command: postgres -c shared_buffers=256MB -c max_connections=200

Troubleshooting :icon

Q: Archives not generating?
A: Check container logs: docker logs link_app
Ensure enough disk space is available

Q: "Database connection failed"?
A: Verify DATABASE_URL is correct
Check link_db container is running: docker ps

Q: Can't login?
A: Reset password via forgot password link
Or reset via database if needed

Q: Browser extension not connecting?
A: Verify server URL matches exactly
Check if you can access web interface
Try re-authenticating in extension

Q: Search not finding content?
A: Full-text search needs archives
Wait for archive generation to complete
Check archives exist for that bookmark

Q: Slow performance?
A: Check database needs vacuuming
Consider limiting archive quality/types
Ensure adequate server resources

Security Best Practices :icon

Authentication

  • :icon{name="lucide:lock"} Use strong, unique passwords
  • :icon{name="lucide:key"} Enable 2FA when available
  • :icon{name="lucide:users"} Create separate accounts for team members
  • :icon{name="lucide:eye-off"} Never share passwords

API Tokens

  • :icon{name="lucide:key"} Generate separate tokens per integration
  • :icon{name="lucide:refresh-cw"} Rotate tokens regularly
  • :icon{name="lucide:trash"} Revoke unused tokens
  • :icon{name="lucide:lock-keyhole"} Store tokens securely (not in code!)

Network Security

  • :icon{name="lucide:globe"} HTTPS only (Traefik provides this)
  • :icon{name="lucide:shield"} Keep containers updated
  • :icon{name="lucide:database"} Database not exposed externally
  • :icon{name="lucide:hard-drive"} Regular backups

Data Privacy

  • :icon{name="lucide:server"} All data on your server
  • :icon{name="lucide:lock"} Not sent to third parties
  • :icon{name="lucide:eye"} Full control over who sees what
  • :icon{name="lucide:trash"} Permanent deletion when you delete

Data & Volumes

PostgreSQL Data

Volume: link_db_data
Contains:
├── Database files
├── User accounts
├── Bookmark metadata
└── Search indices

Application Data

Volume: link_data
Contains:
├── screenshots/     # Bookmark screenshots (PNG)
├── archives/        # PDF archives
├── htmlarchives/    # Full HTML archives
└── uploads/         # User uploaded files

Storage Growth:

  • Each bookmark: ~500KB - 5MB (depends on page)
  • Plan disk space accordingly
  • Monitor with du -sh in container

Ports & Networking

  • App Port: 3000 (internal)
  • Database Port: 5432 (internal only)
  • External Access: Via Traefik at https://link.localhost
  • Network: kompose (isolated, secure)

Useful Commands

View Logs

# Application logs
docker logs link_app -f

# Database logs
docker logs link_db -f

# Both simultaneously
docker compose logs -f

Check Status

# Container status
docker compose ps

# Resource usage
docker stats link_app link_db

Restart Services

# Restart all
docker compose restart

# Restart just app
docker compose restart link_app

Database Console

# Access PostgreSQL
docker exec -it link_db psql -U linkwarden linkwarden

# Useful queries
SELECT COUNT(*) FROM links;  -- Count bookmarks
SELECT * FROM users;         -- List users

Import From Other Services

Pocket

  1. Export from Pocket (HTML or JSON)
  2. Linkwarden → Import
  3. Select Pocket format
  4. Upload and import

Browser Bookmarks

  1. Export from browser (Bookmarks → Export)
  2. Linkwarden → Import
  3. Select "HTML Bookmarks"
  4. Map to collections
  5. Import

Other Services

Supports imports from:

  • Raindrop.io
  • Instapaper
  • Pinboard
  • Any service with HTML/JSON export

Export Your Data

Never locked in! Export anytime:

  1. Settings → Export
  2. Choose format:
    • HTML (browser compatible)
    • JSON (full data)
    • CSV (spreadsheet)
  3. Include options:
    • Archives
    • Screenshots
    • Tags
  4. Download

Why Self-Host Your Bookmarks?

  • :icon{name="lucide:server"} Control: Your data, your rules
  • :icon{name="lucide:eye-off"} Privacy: No tracking or data mining
  • :icon{name="lucide:archive"} Permanence: Archives survive link death
  • :icon{name="lucide:search"} Search: Full-text across all content
  • :icon{name="lucide:users"} Collaboration: Share with your team
  • :icon{name="lucide:zap"} Speed: Local network = instant
  • :icon{name="lucide:dollar-sign"} Cost: Free and unlimited
  • :icon{name="lucide:ban"} No Limits: Unlimited bookmarks and storage

Use Cases & Inspiration

Personal Knowledge Base

Bookmark articles, tutorials, and documentation. Build your second brain!

Research Collection

Gather sources for projects, papers, or investigations. Full archives mean citations never break.

Recipe Archive

Save recipes with full page archives. Even if the blog dies, you keep the recipe!

Travel Planning

Bookmark hotels, attractions, articles. Share collection with travel companions.

Design Inspiration

Screenshot-perfect for saving design examples and mockups.

Dev Resources

Keep tutorials, docs, Stack Overflow answers. Full-text search across all.

Shopping Research

Save product pages with prices and reviews before they change.

News Clipping

Archive news articles before they're paywalled or deleted.

Resources

"The internet is ephemeral. Your bookmarks don't have to be." - A wise bookmark hoarder :icon{name="lucide:bookmark"}:icon{name="lucide:sparkles"}

Reference in New Issue View Git Blame Copy Permalink