Damselfly on AWS

This image delivers Damselfly 4.5.3, the open source self-hosted, server-based photograph management and de-duplication application, fully installed and secured behind an nginx TLS reverse proxy. Damselfly indexes an extremely large collection of images and makes them fast to search and retrieve using IPTC keyword tags, folder names and file names, with a modern browser interface for browsing, tagging, basket/download and optional on-device object and face detection.

Damselfly runs as the official webreaper/damselfly container (pinned by digest) under systemd, published on the host loopback interface only. nginx sits in front on port 443, terminating TLS with a per-instance self-signed certificate and proxying the SignalR WebSocket traffic the UI relies on. Port 80 redirects to HTTPS. Your photo library, the SQLite search index and the thumbnail cache all live on a dedicated, independently-resizable EBS data volume mounted at /var/lib/damselfly, separate from the operating system disk. Damselfly is licensed under the GNU General Public License v3.0.

Secure by default

Stock Damselfly ships with authentication turned off, which leaves every image open to anyone who can reach the server, and once authentication is enabled the first person to register becomes the administrator. This image is different:

• Damselfly's own authentication is on by default (ForceLogin), self-registration is disabled, and a single admin user is seeded.
• An nginx HTTP Basic Auth gate sits in front of the whole application. Damselfly's ForceLogin only protects the Blazor UI - its raw-image and REST endpoints (for example /rawimage/{id}) are not auth-checked on their own, so without this gate the photo library would be downloadable by anyone who could reach port 443. The gate makes the login page the only surface reachable without a credential (apart from the /healthz load-balancer probe).
• A unique administrator password is generated on each instance's first boot, used for both the nginx gate and the Damselfly login, and written to a root-only file. Only a one-way PBKDF2 hash is stored in the database - never the plaintext.
• The security group opens only SSH (22) and HTTPS (443). The application itself is bound to loopback and is never exposed over plain HTTP or left world-open.

There are no shared or default credentials, and nothing is baked into the image - no two deployments are ever the same.

Connecting to your instance

Connect over SSH on port 22 using the default login user for your operating system variant and the EC2 key pair you launched with.

Replace <instance-public-ip> with your instance's public IPv4 address (or its private address if you reach it over a VPN or Direct Connect). Scope the security group's 22 and 443 rules to your own network.

Retrieve your admin password

Each instance generates its own admin credential on first boot and writes it to a root-only file. Read it over SSH:

sudo cat /root/damselfly-credentials.txt

You will see the admin username (admin), the login email (admin@damselfly.local), the per-instance password, and the HTTPS URL for your instance. Keep this file secret.

Sign in

Open Damselfly in your browser over HTTPS:

https://<instance-public-ip>/

Signing in is a two-step flow, and the same password is used for both:

1. The certificate is self-signed per instance, so your browser shows a one-time certificate warning - accept it to proceed (replace the certificate with a CA-signed one for production; see the TLS section below).
2. Your browser then shows an HTTP authentication prompt - this is the nginx security gate that keeps the photo library private. Enter username admin and the password from the credentials file.
3. Finally, Damselfly's own Log In page appears - sign in with the email (admin@damselfly.local) and the same password.

Once signed in you land on the gallery. A small set of sample photos is included so the gallery is populated immediately, with a folder tree, keyword tagging, a basket for downloads, and a fast search bar across the top.

Adding your own photos

Your library lives on the dedicated data volume at /var/lib/damselfly/pictures. Copy your own photos there, then rescan from the UI. For example, upload from your workstation with rsync (replace the placeholders with your own paths and address):

rsync -av -e "ssh -i your-key.pem" /path/to/your/photos/ ubuntu@<instance-public-ip>:/tmp/df-upload/
sudo rsync -a /tmp/df-upload/ /var/lib/damselfly/pictures/ && rm -rf /tmp/df-upload

Damselfly watches the pictures folder and indexes new files automatically; you can also trigger a rescan from the folder view. Because the library is on its own EBS volume, you can grow it independently of the operating system disk as your collection expands.

Optional object and face recognition

Damselfly can scan your images locally, on-device, to detect objects and faces so you can find photos by what is in them. This is off by default to keep CPU usage low - the bundled ONNX models run on the CPU only, with no GPU and no external service. Enable it when you want it under Config -> Image Recognition: tick Scan images locally for objects/faces using AI, untick Disable object detection scanner, set a CPU usage limit that suits your instance, and save.

Configuration

The Config page (the admin link in the footer) groups every setting - user settings and theme, image recognition, email notifications, WordPress publishing, user management and system settings.

Verifying the deployment

The checks below confirm the appliance is healthy. Run them over SSH.

The three services that make up the appliance - the Docker runtime, the Damselfly container and the nginx TLS proxy - should all report active:

systemctl is-active docker.service damselfly.service nginx.service

The unauthenticated health probe on the HTTPS listener returns 200, and plain HTTP on port 80 returns a 301 redirect to HTTPS:

curl -ks -o /dev/null -w 'healthz -> %{http_code}\n' https://127.0.0.1/healthz
curl -s -o /dev/null -w 'port 80 -> %{http_code} %{redirect_url}\n' http://127.0.0.1/

The Damselfly container is published on the host loopback interface only (127.0.0.1:6363) - never on a public address; nginx is the sole network-facing surface:

ss -H -tln 'sport = :6363'

The exact Damselfly version and pinned image digest shipped in this AMI:

cat /opt/damselfly/VERSION

The sample photos included so the gallery is populated on first launch:

ls -1 /var/lib/damselfly/pictures

Finally, the built-in self-test proves the end-to-end security model over TLS in one command: authentication is enabled, a wrong password is refused, and the per-instance credential authenticates and returns a JWT:

/usr/local/bin/damselfly-selftest

A healthy instance prints OK damselfly self-test passed: auth enabled (ForceLogin), wrong pw refused, per-VM login returns a JWT (TLS).

Enabling HTTPS with your own certificate

The image ships a per-instance self-signed certificate at /etc/nginx/tls/damselfly.crt and /etc/nginx/tls/damselfly.key, which is why browsers show a warning. For production, point a DNS name at your instance and replace the certificate with a CA-signed one (for example from Let's Encrypt), then reload nginx. Keep the security group's 443 rule scoped to the networks that should reach your photo library.

Support

cloudimg provides 24/7 technical support for this product by email and live chat. Our engineers help with deployment, library configuration, TLS and certificate setup, object and face recognition tuning, data-volume sizing, and runtime tuning.

• Email: support@cloudimg.co.uk
• Live chat: available 24/7 through the cloudimg support portal