Elk: A Nimble Mastodon Web Client That Leaves TLS to You
A nimble Mastodon web client. The Docker container itself does not provide any SSL/TLS handling.
At a glance
- What is it?
- Elk is a Vue and Nuxt based Mastodon web client that you can self-host with Docker, but the container ships without SSL/TLS handling, so you must put a reverse proxy in front of it. This review covers what Elk does, how to run it, and where the sharp edges are.
- Who is it for?
- Adopt Elk if you want a fast, modern Mastodon web client that you can self-host and that works with any compatible instance. Do not adopt it if you expect a turnkey deployment with built-in TLS or if you cannot manage a reverse proxy and file permissions on a Docker volume.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 13 days ago.
- What is it written in?
- Mainly Vue, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Elk Actually Solves
Elk is a web client for Mastodon, the federated social network. It solves the problem of using Mastodon from a browser without relying on the default web interface that ships with your instance. The README calls it "a nimble Mastodon web client," which suggests the project focuses on speed and a clean user experience. The target audience is people who want more control over their Mastodon frontend, either for themselves or for a community. The project also serves as a base for other fediverse projects, as the list of known deployments shows. If you run a Mastodon server and want to offer a different interface to your users, Elk gives you that option.
How Elk Works Under the Hood
Elk is built on a specific stack that the README lists: Vite for tooling, Nuxt as the web framework, Vue for components, VueUse for composition utilities, Pinia for state management, and UnoCSS for styling. The Mastodon API interaction is handled by Masto.js, a TypeScript client for the Mastodon API. This means Elk is not just a static page; it is a full client that talks to the Mastodon API directly from the browser. The data flow is straightforward: you log in through Elk, it uses Masto.js to authenticate against your Mastodon instance, and then it fetches and posts statuses through that API. The PWA capabilities, mentioned in the README, add offline support and push notifications, which are handled by vite-plugin-pwa. The container itself is built with a Dockerfile, and the README warns that it runs as a non-root user with UID:GID 911, which is a specific detail that affects how you manage storage.
Getting Elk Running: Commands and Configuration
The README gives a clear set of commands for self-hosting via Docker. You start by cloning the repository: `git clone https://github.com/elk-zone/elk.git`, then `cd elk`. You must create a local storage directory for settings with `mkdir elk-storage`, and then adjust its permissions with `sudo chown 911:911 ./elk-storage`. Finally, you start the container with `docker compose up --build -d`. That is the whole setup as documented. The key configuration point is the storage directory. The README notes that the Dockerfile creates a persistent named volume on first start, and that volume is created with root permissions. If you do not change the permissions of `/elk/data` inside that volume to UID:GID 911, Elk will not be able to store configuration for user accounts. You have two options: fix the permissions inside the named volume, or mount a directory with the correct permissions to `/elk/data`. This is a concrete operational detail that you cannot skip.
The TLS Catch: No SSL/TLS in the Container
The README is explicit: "The Docker container itself does not provide any SSL/TLS handling." This is a genuine limitation. Elk only loads properly over an SSL/TLS connection, which means you cannot just run the container and access it over plain HTTP and expect it to work. The README suggests putting Elk behind a reverse proxy that handles SSL/TLS, such as Traefik or NGINX. This is not a minor detail; it is a deployment requirement. If you are used to containers that bundle a web server with TLS configured, Elk will surprise you. You must add that layer yourself. This also means that for a production deployment, you need to manage certificates, proxy configuration, and possibly WebSocket upgrades, depending on how Mastodon streams updates. The README does not mention WebSockets, but any real-time feed would need them. The documentation does not cover that, so you would have to figure it out on your own.
Storage Permissions: The Silent Failure Mode
The README warns about a specific failure mode: if the `/elk/data` directory inside the Docker volume has the wrong permissions, Elk will not store configuration for user accounts. This is not a crash; it is a silent problem where user settings might not persist. The README says the volume is always created with root permissions, and you need to change them to UID:GID 911. This is a common Docker pitfall, but Elk makes it explicit. The given command `sudo chown 911:911 ./elk-storage` works for a bind mount, but if you rely on the named volume, you have to fix permissions inside the volume, which is more involved. This is a case where the project's documentation is honest about a rough edge. If you ignore this, you will end up with a client that works but forgets user preferences, which is confusing for users.
Alternatives and the Difference in Approach
A real alternative to Elk is the default Mastodon web interface that ships with every Mastodon server. That interface is tightly integrated with the server and requires no separate deployment. The difference in approach is that the default interface is part of the server software, so you get TLS and storage handled by the server's own setup. Elk, by contrast, is a separate client that you deploy independently, which gives you more control over the frontend but also more operational responsibility. Another alternative is to use a hosted Mastodon client service, but the README lists community deployments that are not maintained by the Elk team. Those deployments might be easier to use, but they come with trust concerns. The core difference is that Elk is self-hosted and requires you to manage the full stack, while the default interface is just there.
Maintenance and License Implications
Elk is under the MIT license, as stated in the README. This means you can use, modify, and distribute it freely, with attribution. The project is actively maintained, with recent releases including v1.0.1 in July 2026 and v1.0.0 in June 2026. That suggests a stable release cadence. The maintenance cost for you comes from keeping up with releases, rebuilding the Docker image, and managing the reverse proxy and storage. The README mentions a canary deployment at main.elk.zone that deploys on every commit to the main branch, which indicates a fast-moving project. You will need to decide whether to track stable releases or live on the edge. The license does not impose restrictions on commercial use, but it does not provide any warranty, so you are responsible for your deployment. The project also encourages contributions and has a contributing guide, so if you find a bug, you can fix it and submit a pull request.
Editorial conclusion
Adopt Elk if you want a fast, modern Mastodon web client that you can self-host and that works with any compatible instance. Do not adopt it if you expect a turnkey deployment with built-in TLS or if you cannot manage a reverse proxy and file permissions on a Docker volume. Before you deploy, verify that your reverse proxy terminates SSL/TLS correctly, that the /elk/data volume or mounted directory is owned by UID:GID 911, and that your Mastodon server is compatible with the Masto.js API client. If you need a client with integrated TLS or a simpler install, look elsewhere or be prepared to add that layer yourself.
Community notes