Getting Started

Overview Linkwarden Features & Key Concepts

GitHub-logo.pnglinkwarden.pngLive-Demo


Introduction

Linkwarden is a self-hosted, open-source bookmark manager designed to help individuals and teams collect, organize, and preserve web content. It not only functions as a tool to save and categorize important links but also ensures that the content remains accessible even if the original webpage is no longer available. By automatically saving web pages as screenshots, PDFs, and HTML files, Linkwarden combats the issue of "link rot"—the phenomenon where useful webpages disappear or change over time.

Designed with collaboration in mind, Linkwarden allows multiple users to share and work together on collections of bookmarks. It offers seamless integration with services like the Wayback Machine, and for larger organizations, it provides SSO (Single Sign-On) support and various enterprise-level features.

Features

Public RoadmapRoadmap.png

Key Concepts

  1. Bookmark Preservation: Linkwarden ensures that your bookmarked webpages remain accessible even if the original content is removed or altered. The tool automatically saves copies in multiple formats such as screenshots and PDFs.

  2. Collaborative Bookmarking: Designed for teamwork, Linkwarden allows multiple users to organize and manage collections of bookmarks. This is particularly useful for research projects, group work, or knowledge-sharing within organizations.

  3. Flexible Organization: Users can create collections, sub-collections, and assign tags to bookmarks, making it easy to categorize and retrieve relevant links quickly.

  4. API and Automation: Linkwarden supports API key generation, enabling users to integrate it with other tools or automate processes like bulk bookmarking or custom searches.

  5. Multi-Platform Accessibility: With its responsive design, Linkwarden works across desktop, mobile, and tablet devices. It also offers browser extensions and a Progressive Web App for added convenience.

  6. Security and Privacy: Linkwarden provides security features such as Single Sign-On (SSO) for enterprise users, ensuring secure access to sensitive information.

Conclusion

Linkwarden is a versatile, self-hosted solution for managing bookmarks with a focus on collaboration, preservation, and accessibility. Whether you’re an individual wanting to keep your personal reading list organized or a team collaborating on a project, Linkwarden offers the tools you need to save, categorize, and share web content efficiently. The combination of advanced features like API support, SSO, and automated preservation mechanisms makes it a powerful tool for users who need more than just a standard bookmark manager.

By supporting multiple platforms, offering collaboration features, and ensuring security through privacy-focused options, Linkwarden is an excellent choice for both personal use and enterprise-level teams.

Step-by-Step Install Guide for Linkwarden with Traefik on Docker Swarm

logo.png

GitHub-logo.pngIntroduction

In this guide, we'll walk through the process of installing Linkwarden, a self-hosted bookmark manager, on Docker Swarm. This installation will include setting up Traefik as the reverse proxy and configuring persistent storage using GlusterFS. Additionally, we'll cover how to securely set up environment variables, such as the NEXTAUTH_SECRET, and ensure proper file permissions using a custom Linux user.

Step 1: Create a User for Linkwarden Folders

To ensure that only one Linux user has the necessary rights for the Linkwarden folders, we'll create a custom user and group called linkwardenuser. This user will not have a home directory, and the shell will be set to /usr/sbin/nologin for security purposes.

  1. Create the custom user and group with the GID and UID set to 10002:

    sudo groupadd -g 10002 linkwardenuser
sudo useradd -u 10002 -g linkwardenuser -s /usr/sbin/nologin -M linkwardenuser
    • The -s /usr/sbin/nologin option ensures that this user cannot log in interactively, which is a security best practice for service users.
    • The -M option prevents the creation of a home directory, as this user will only be managing Linkwarden's folder permissions and not need a home directory for other purposes.

Step 2: Create Folders for Linkwarden

Next, we’ll create the necessary folders to store Linkwarden’s data on the GlusterFS mount.

  1. Create the folders for Linkwarden's data:

    mkdir -p /mnt/glustermount/data/linkwarden_data
mkdir -p /mnt/glustermount/data/linkwarden_data/pgdata
mkdir -p /mnt/glustermount/data/linkwarden_data/lwdata
mkdir -p /mnt/glustermount/data/linkwarden_data/storage
  2. Adjust ownership of these folders to the linkwardenuser, ensuring all files inside are accessible to this user:
    This ensures that only the linkwardenuser has access to these folders and files, maintaining data security.
    sudo chown -R linkwardenuser:linkwardenuser /mnt/glustermount/data/linkwarden_data


  3. Permissions: The following permissions ensure that the owner (user 10002) has full access (read, write, execute) to the directories and files, and that no one else can modify the files.
    sudo chmod -R 750 /mnt/glustermount/data/linkwarden_data

    750 means:
    - 7: Owner (user 10002) has read, write, and execute permissions.
    - 5: Group has read and execute permissions (but not write).
    - 0: Others have no permissions.



Step 3: Create docker-compose.yaml

Now, we’ll create the Docker Compose file that will define two services: one for Linkwarden and another for its PostgreSQL database. We will also configure Traefik to route traffic to Linkwarden.

To Configure the Composefile check out the ENVIROMENT-VARIABLES Wiki Article.

version: "3.5"

services:
  linkwarden:
    image: ghcr.io/linkwarden/linkwarden:latest
    environment:
      - DATABASE_URL=postgresql://linkwarden:${POSTGRES_PASSWORD}@postgres:5432/linkwardendb
      - NEXTAUTH_URL=http://localhost:3000/api/v1/auth
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - STORAGE_FOLDER=/mnt/glustermount/data/linkwarden_data/storage
      - NEXT_PUBLIC_EMAIL_PROVIDER=${NEXT_PUBLIC_EMAIL_PROVIDER}
      - EMAIL_FROM=${EMAIL_FROM}
      - EMAIL_SERVER=${EMAIL_SERVER}
      - BASE_URL=${BASE_URL}
      - TZ=Europe/Zurich
      - GID=10002
      - UID=10002
    restart: always
    ports:
      - 3000:3000
    volumes:
      - /mnt/glustermount/data/linkwarden_data/lwdata:/data/data
    depends_on:
      - postgres
    networks:
     - management_net
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.role == manager
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.linkwarden.rule=Host(`linkwarden.domain.tld`)"
        - "traefik.http.services.linkwarden.loadbalancer.server.port=3000"
        - "traefik.http.routers.linkwarden.entrypoints=websecure"
        - "traefik.http.routers.linkwarden.tls.certresolver=leresolver"

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: linkwarden
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: linkwardendb
      TZ: Europe/Zurich
      GID: 10002
      UID: 10002
    restart: always
    volumes:
      - /mnt/glustermount/data/linkwarden_data/pgdata:/var/lib/postgresql/data
    ports:
      - 5432:5432
    networks:
     - management_net
    deploy:
      replicas: 1
      placement:
        constraints:
          - node.role == manager
      labels:
        - "traefik.enable=true"
        - "traefik.http.services.postgres.loadbalancer.server.port=5432"

networks:
  management_net:
    external: true
SMTP Settings

Step 4: Create the NEXTAUTH_SECRET

The NEXTAUTH_SECRET is used to sign authentication tokens securely. You need to generate a random string to be used as the NEXTAUTH_SECRET.

You can generate a secure NEXTAUTH_SECRET using the following command:

openssl rand -base64 32

This command will generate a 32-byte random string that you can add to your .env file as the NEXTAUTH_SECRET.

What Does NEXTAUTH_SECRET Do?

The NEXTAUTH_SECRET is critical for securing the authentication process in Linkwarden. It is used to sign and encrypt tokens, ensuring that user sessions are protected from tampering or unauthorized access.

Step 5: Start the Stack

Once everything is configured, you can start the Linkwarden stack either manually or through Portainer.

Start with Docker Swarm

To start the stack manually, run:

docker stack deploy -c docker-compose.yaml linkwarden
Start with Portainer

Alternatively, you can use Portainer’s graphical interface to import the docker-compose.yaml file and start the stack.

Once the stack is deployed, Linkwarden will be available at https://linkwarden.domain.tld (or whatever domain you've configured).

Conclusion

This guide provides a detailed walkthrough for setting up Linkwarden with Traefik on Docker Swarm. From user and folder management to Docker Compose configuration, these steps ensure a secure and scalable deployment of your self-hosted bookmark manager.