How to Use Glance: The Beginner's Guide

CodexFuse Team · 2026-11-02T22:22:15.747Z · 14 min read min read

Glance is the self-hosted dashboard that puts all your feeds in one place. This beginner guide covers the Docker deploy, the glance.yml rule, pages and widgets, server stats, and the new built-in login.

What Is Glance, Exactly?

Glance is a free, open-source, self-hosted dashboard that puts all your feeds in one place: RSS feeds, weather, your calendar, YouTube uploads, Twitch channels, Hacker News, subreddits, stock prices, server stats, and Docker container status, arranged as widgets on customizable pages. It is a single small Go binary (under 20 MB) or an equally small Docker container, it stores nothing in a database, and you configure the entire dashboard through one YAML file called glance.yml. If you want a start page that shows your information instead of just linking to it, that is the lane Glance owns. The Homepage beginner guide covers the sibling dashboard for people who mainly want fast service links, while this guide shows you how to use Glance's feed-and-widget approach for a homelab start page.

One disambiguation up front, because the name collides: this is Glance the homelab dashboard from the glanceapp project on GitHub, not InMobi's Glance lock-screen content app and not OpenStack's Glance image service. Everything below is about the self-hosted dashboard.

How Do You Install Glance with Docker Compose?

The fastest reliable path is Docker Compose with the project's official template: it gives you a working dashboard in about five minutes. The Glance Docker setup needs just one image, one volume, and one port. You need Docker and Docker Compose installed first, which the Docker beginner guide to Compose walks through if you have never touched them. Then follow this arc:

1. Create the project folder and pull the template. Run mkdir glance && cd glance && curl -sL https://github.com/glanceapp/docker-compose-template/archive/refs/heads/main.tar.gz | tar -xzf - --strip-components 2. This gives you a docker-compose.yml, a config/ folder with home.yml and glance.yml, an assets/user.css file for custom styling, and a .env file for environment variables.
2. Look at the compose file before you start it. The template runs the glanceapp/glance image, mounts ./config to /app/config inside the container, and publishes port 8080:8080. You rarely need to change anything here on a first run.
3. Start it. Run docker compose up -d inside the folder. Glance reads your YAML, validates it, and starts serving.
4. Open the dashboard. Visit http://localhost:8080 in your browser (replace localhost with your server's address if Glance runs on another machine). The template ships with a preconfigured home page so you see a full dashboard immediately, not a blank screen.
5. Check the logs if anything looks wrong. Run docker compose logs. A YAML indentation error is the most common first-run failure, and the log tells you exactly which line broke.

Prefer to write the compose file yourself instead of using the template? The manual version is short: one service using glanceapp/glance, restart: unless-stopped, the ./config:/app/config volume, and 8080:8080 for ports. Download the example glance.yml into a config folder first, then docker compose up -d. A plain binary install exists too for Linux, Windows, and macOS, where the binary looks for glance.yml in its own directory unless you pass --config.

What Is the glance.yml Rule?

The glance.yml rule is this: the YAML file is the entire application. There is no database, no settings page in the UI, and no state stored anywhere else. Every page, every column, every widget, the theme, and the login users all live in YAML. Delete the config and you have deleted your whole dashboard; back the config up and you have backed up everything.

This has three practical consequences beginners should internalize early. First, YAML indentation errors break the whole dashboard, so validate before you save: Glance exits with an error if you start it with an invalid config. Second, Glance supports automatic config reload, so edits take effect on save without restarting the container. If you edit a running config into an invalid state, Glance keeps serving the old working config and prints the error in the console, which makes experimentation safe. Third, reloading the config clears cached widget data, so the next page load re-fetches everything; hammering save can get you rate-limited by APIs like Reddit's, so edit in batches.

Secrets deserve their own rule inside the YAML rule: API tokens and passwords never go in plaintext in the file. The template's .env file exposes environment variables inside your configuration, and the docs' server-settings section plus the auth section both assume you keep credentials in env vars or hashed form. Your Glance config is also your backup strategy: commit your glance.yml to a private git repo all you like, just never with a live token in it.

How Do Pages, Columns, and Widgets Fit Together?

A Glance dashboard is a strict hierarchy: pages contain columns, columns contain widgets, and widgets are the individual cards that show your data. A Glance page is a tab in the navigation bar. Each page has columns of size small or full. Each column holds an ordered list of widgets. The README's own example shows the classic layout: two small columns flanking one full column, with a calendar and RSS feeds on the left, Hacker News, Reddit, and YouTube in the middle, and weather and markets on the right.

Glance pages can live in separate files, which keeps one monster YAML manageable. The compose template splits them already: config/glance.yml holds the theme and the page list, while config/home.yml holds the actual Home page content. The classic beginner error here produces the message cannot unmarshal !!map into []glance.page: it means you have a pages key at the top of glance.yml and another pages key inside an included page file. Remove the duplicate and the error goes away.

Two layout helpers are worth knowing early. The group widget bundles several widgets into one card so related feeds share a frame, and split-column divides a column further. Between these and the small/full column sizes, you can build surprisingly dense dashboards without any CSS.

Which Glance Widgets Should a Beginner Add First?

Start with the widgets that need zero credentials: RSS, weather, calendar, clock, Hacker News, and bookmarks. Add the credential-hungry ones only after your layout feels right. The catalog is large, and the docs group it by type. Here is a beginner's map of the ones that matter most:

The videos widget trips up beginners for a mechanical reason: it wants YouTube channel IDs, not channel names. Open a channel page, view the page source, and search for /channel/; the ID is the string after it. The reddit widget has a subtler gotcha worth knowing before you deploy: Reddit blocks unauthorized API access from VPS IP addresses with a 403, and since v0.8.7 the widget's search property only works when app-auth is configured with a generated client ID and secret. On a home connection you can often skip this; on a VPS, configure app-auth or route the requests through a proxy.

How Do You Add Server Stats to Your Glance Dashboard?

Add a server-stats widget with a local server entry for the machine Glance runs on, and use the Glance Agent only for remote machines. The minimal config is three lines: the widget type, a servers list, and one entry with type: local and a display name. You get CPU, memory, disk, and swap usage, with mountpoints you can show, hide, or rename per path. If the CPU temperature crosses 80 degrees Celsius, a flame icon appears next to it, which is a genuinely useful at-a-glance warning on a NAS or a passively cooled mini PC.

Two honest caveats. First, when Glance runs in Docker, "local" means the container's view of the system, not your host's full hardware picture; for host-level stats many people run the binary directly or accept the container's numbers. Second, the widget is officially still under development, so expect occasional rough edges. For remote machines, Glance server stats need the separate Glance Agent, which is also in development. The related docker-containers widget is the one homelab owners actually check daily, and it has one hard requirement: mount /var/run/docker.sock into the Glance container or it cannot see your containers at all.

How Does Glance Compare to Homepage and Dashy?

Glance is the feeds dashboard, Homepage is the links dashboard, and Dashy is the status-check dashboard. Pick the one whose main job matches yours. The Glance vs Homepage question comes up constantly in homelab circles because both are YAML-configured and both can be a start page, but they optimize for different mornings. The Glance vs Dashy comparison is simpler: pick Glance for feeds, Dashy for status checks. All three are self-hosted, and all three can run on the same homelab. The difference is what each one is best at showing:

Nothing stops you from running two of them: many homelabs use Homepage as the app launcher and Glance as the information page. The Dashy beginner guide covers the third corner of this triangle if you want to compare all three hands-on before committing.

How Do You Run Glance on a Synology NAS?

On a Synology NAS, run Glance as a Portainer stack with your config folder on a Docker share and port 8080 mapped to an unused host port like 6659. The freshest end-to-end walkthrough for this path, updated within the last day and tested against v0.8.7, uses Portainer's stack editor: image glanceapp/glance:latest, a volume mapping your NAS folder to /app/config read-write, the Synology timezone files mounted read-only so the calendar and clock show the right time, and 6659:8080 in the ports section. Open http://your-nas-ip:6659 and the dashboard appears.

If you have never used Portainer's stack feature, the Portainer beginner guide covers stacks from zero. Either way, your Glance homelab dashboard is one stack deploy away. One Synology-specific tip: create the glance folder and drop your edited glance.yml into it through File Station before deploying the stack, so the container finds its config on the first start instead of serving the default page and confusing you.

How Do You Lock Glance Down?

Glance now ships with built-in username-and-password authentication, and you should enable it before exposing the dashboard anywhere beyond your LAN. Older guides still claim Glance has no auth at all; that changed in the v0.8 series, so treat those guides as outdated. The setup is two CLI commands and one YAML block. First generate the secret key with glance secret:make, or docker run --rm glanceapp/glance secret:make if you run the container. Then add a top-level auth section to glance.yml with that secret key and your users.

Do not store plaintext passwords even in a private config. Hash each password with glance password:hash yourpassword (same Docker one-liner works) and put the resulting bcrypt hash in the password-hash property instead of password. Glance also blocks IP addresses automatically after five failed logins in five minutes, which blunts brute-force guessing. If Glance sits behind a reverse proxy like Nginx, Traefik, or NPM, set server.proxied: true so it reads the real client IP from the X-Forwarded-For header; without it, the brute-force blocking sees only your proxy's address. Whether you self-host on a home server or rent one, the what is VPS hosting guide explains the machine side of this setup, and a VPS deployment is exactly where the Reddit 403 problem from the widgets section bites, so configure that app-auth too.

What Trips Beginners Up?

Almost every Glance failure is one of seven beginner mistakes, and all seven are fixed in the config file, not in Docker. Keep this table next to your editor for the first week:

Sources

1. Glance README, github.com/glanceapp/glance (fetched 2026-11-03): install methods, compose template, glanceapp/glance image, port 8080, no-database design, widget list, themes, community widgets, preconfigured pages.
2. Glance configuration docs, docs/configuration.md, glanceapp/glance (fetched 2026-11-03): auth property with secret:make and password:hash CLI commands, brute-force IP blocking, server.proxied, auto-reload behavior, pages/columns/widgets structure, full widget property reference including app-auth, server-stats remote agent, and docker-containers socket requirement.
3. Glance v0.8.7 release notes, github.com/glanceapp/glance/releases (fetched 2026-11-03): latest release; Reddit widget fix with the app-auth requirement for search; DNS stats, RSS, and monitor widget fixes.
4. Marius Hosting, "How to Install Glance on Your Synology NAS" (updated 2026-11-02): Portainer stack walkthrough tested against v0.8.7, 6659:8080 port mapping, timezone mounts.
5. Ramdi.fr, "Glance: a minimal self-hosted dashboard with YAML-driven widgets and stateless caching" (2026): architecture analysis of the YAML-driven, database-free, per-widget-cache design.
6. XDA Developers, two Glance setup guides (2026): browser-homepage arc and the YAML-intimidation-to-easy walkthrough with themes and community widgets.
7. DeepWiki, "Getting Started" for glanceapp/glance (2026): config validation on startup, --config flag, pre-v0.7 migration handler, CLI structure.

Frequently Asked Questions

Does Glance have a database?

No. Glance is completely stateless: your entire dashboard lives in YAML files, and widget data is fetched on page load and held in a per-widget cache. There is nothing to back up except your config folder, and nothing to migrate when you move servers.

Does the Glance dashboard update automatically?

No. The project FAQ is explicit: no requests happen in the background, so you refresh the page to get new data. The clock widget and relative timestamps update live in the browser, but feeds, stats, and videos only re-fetch on load, honoring each widget's cache lifetime.

Does Glance have authentication?

Yes, since the v0.8 series. Add a top-level auth block with a secret key from glance secret:make and users with bcrypt hashes from glance password:hash. Failed logins are rate-limited by IP, and you should still avoid exposing it directly to the internet without a reverse proxy and HTTPS.

Can I use Glance on a Synology NAS or Raspberry Pi?

Yes. The Docker image supports x86 and ARM, so it runs on a Pi, and the Synology path is a Portainer stack with your config folder mounted and port 8080 mapped to a free host port such as 6659. The single binary is also under 20 MB if you prefer running it directly.

What is the difference between Glance and Homepage?

Glance is built around feeds and information widgets: RSS, YouTube, weather, server stats, and markets on a morning-briefing page. Homepage is built around service links and status cards: a fast launcher for the dozens of apps in a homelab. Many people run both, each doing the job it is best at.