Linkwarden on AWS User Guide

Overview

This image runs Linkwarden, the open source self-hosted bookmark manager and web archive. Linkwarden lets you collect links into collections, organise them with tags and search across everything full text. For every link it saves, Linkwarden automatically preserves a screenshot, a PDF, a single file HTML copy and a readable text snapshot, so the content survives even when the original page changes or disappears.

The Next.js web application is served on port 3000 and a background worker performs the page archiving. An nginx reverse proxy on port 80 sits in front of the application. A local PostgreSQL 16 database holds the link metadata. Page archiving uses Playwright Chromium for screenshots and PDFs and the monolith engine for full page HTML capture, all on the same instance.

A Linkwarden administrator account is generated on the first boot of every deployed instance, together with a fresh authentication secret and a fresh PostgreSQL password. Two instances launched from the same Amazon Machine Image never share credentials. The administrator username and password and the database password are written to /root/linkwarden-credentials.txt with mode 0600 so that only the root user can read them. Open self registration is disabled, so no one can sign themselves up; the administrator adds further users from the Linkwarden settings.

The Linkwarden application tree and its archived files live under /opt/linkwarden, on a dedicated EBS volume separate from the operating system disk. The PostgreSQL data directory sits on its own EBS volume at /var/lib/postgresql. Each tier can be resized independently of the others.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users will reach Linkwarden on
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Linkwarden. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger — the page archiving workload runs a headless Chromium browser, which benefits from memory and CPU. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound ports 80 and 443 from the networks your users use. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one to two minutes after the instance state becomes Running and the status checks pass, while the administrator account is seeded.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Linkwarden Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22, 80, and 443 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=linkwarden-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect and Retrieve Initial Credentials

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

The first boot service seeds the administrator account before sign in is possible, so the credentials file is in place when you log in for the first time.

ssh <login-user>@<public-ip>
sudo cat /root/linkwarden-credentials.txt

You will see a plain text file containing the Linkwarden URL, the administrator username (admin), the administrator password, and the PostgreSQL database name, user, and password. Copy these values somewhere secure (a password manager or encrypted vault). Do not commit them to source control.

From the same SSH session you can confirm the deployment is healthy. The Linkwarden service runs the web application and the archiving worker together:

systemctl status linkwarden --no-pager

● linkwarden.service - Linkwarden (Next.js web + archiving worker)
     Loaded: loaded (/etc/systemd/system/linkwarden.service; enabled; preset: enabled)
     Active: active (running)
   Main PID: 53385 (node)
      Tasks: 159
     CGroup: /system.slice/linkwarden.service
             ├─ node /usr/bin/corepack yarn concurrently:start
             ├─ concurrently "yarn workspace @linkwarden/web start" "yarn workspace @linkwarden/worker start"
             └─ ...

The NextAuth session endpoint is open and returns an empty JSON object when you are not signed in, which confirms the web application is serving:

curl -fsS http://127.0.0.1/api/v1/auth/session

{}

Step 4: Sign In to Linkwarden

Open http://<public-ip>/ in your browser. The Linkwarden sign in page appears. Enter the administrator username admin and the password from /root/linkwarden-credentials.txt, then select Login.

After signing in you land on the Linkwarden dashboard, which shows your collections and recently added links.

Step 5: Create a Collection and Save a Link

Collections group related links. Select New Collection in the left sidebar, give it a name and an optional colour and description, and save it. Then select New Link, paste a URL, choose the collection and add any tags, and save. Linkwarden fetches the page title and metadata immediately and queues the page for archiving in the background.

Step 6: How Page Archiving Works

For every link you save, the background worker preserves the page in several formats so the content is durable:

• A full page screenshot and a PDF, captured with a headless Chromium browser through Playwright
• A single file HTML copy, captured with the monolith engine, which inlines images, stylesheets and scripts into one self contained file
• A readable text snapshot, extracted for distraction free reading and full text search

Open a saved link to see its preserved formats. Archiving runs asynchronously, so the formats appear a few moments after you save the link.

The archived files are stored on the dedicated application volume under /opt/linkwarden/data, so they are kept separate from the operating system disk and can be resized or backed up independently.

Step 7: Add More Users

Open self registration is disabled on this image, so the public sign up page is closed. As the administrator you add users from the Linkwarden settings. Select your profile, open Settings, then the user administration area, and create accounts for your team. Each user gets their own collections and links and can be granted access to shared collections.

Step 8: Configure Outbound Email (Optional)

Linkwarden can send email for account related actions when you point it at an SMTP server. Edit the environment file and add your SMTP settings, then restart the service. The environment file lives at /opt/linkwarden/src/.env — open it with your preferred editor, for example sudo nano /opt/linkwarden/src/.env.

Set NEXT_PUBLIC_EMAIL_PROVIDER, EMAIL_FROM and EMAIL_SERVER to your provider's values, save the file, and restart Linkwarden:

sudo systemctl restart linkwarden

Step 9: Enable HTTPS (Optional)

The image serves Linkwarden over plain HTTP on port 80 so it is reachable immediately on its launch address. For production use you should terminate TLS. The simplest path is a Let's Encrypt certificate with Certbot once you have pointed a DNS name at the instance.

Install Certbot and request a certificate for your domain. Certbot edits the nginx configuration in place to add the TLS server block and a redirect from HTTP to HTTPS:

sudo snap install --classic certbot
sudo ln -sf /snap/bin/certbot /usr/bin/certbot
sudo certbot --nginx -d your-domain.example.com

After enabling HTTPS, update NEXTAUTH_URL in /opt/linkwarden/src/.env to your https://your-domain.example.com/api/v1/auth address and restart Linkwarden so the authentication callback URLs match your new address:

sudo systemctl restart linkwarden

Step 10: Backup and Maintenance

Two pieces of state matter for backup: the PostgreSQL database (link metadata, users and collections) and the archived files under /opt/linkwarden/data.

Back up the database with pg_dump:

sudo -u postgres pg_dump linkwarden | gzip > linkwarden-$(date +%F).sql.gz

Back up the archived files by snapshotting the /opt/linkwarden EBS volume from the AWS console or CLI, or by copying /opt/linkwarden/data to object storage. Because the database and the application data live on their own EBS volumes, you can take EBS snapshots of each tier independently.

To update Linkwarden in place, pull the new tag in /opt/linkwarden/src, reinstall dependencies, rebuild and apply migrations, then restart the service. Always take a database dump and an EBS snapshot first. cloudimg support can assist with upgrades and migrations.

Service Management Reference

Support

This is a repackaged open source software product. cloudimg provides 24/7 technical support for the image covering Linkwarden deployment, upgrades, archiving configuration, object storage, search tuning, TLS termination and PostgreSQL administration. Linkwarden itself is licensed under the GNU Affero General Public License version 3. All product and company names are trademarks or registered trademarks of their respective holders.