# FlatNas: a self-hosted browser start page for NAS users and their services

> FlatNas is a personal dashboard that runs on your own machine, built with a Vue 3 front end and a Go back end, and it packs in a file transfer tool, a music player, a Docker controller and a system monitor alongside the bookmarks. The data lives in a local JSON file, and the whole thing starts with a single install script.

**Garry-QD/FlatNas** — FlatNas 是一个轻量级、高度可定制的个人导航页与仪表盘系统。它基于 Vue 3 和 Express 构建，旨在为 NAS 用户、极客和开发者提供一个优雅的浏览器起始页。

- Repository: https://github.com/Garry-QD/FlatNas
- Website: https://flatnas.top/
- Stars: 572 · Forks: 106
- Language: Vue
- License: AGPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/garry-qd-flatnas

## A start page that runs on the machine it describes

FlatNas is described as a lightweight, highly customisable personal navigation page and dashboard system, built with Vue 3 and Go with the Gin framework, intended to give NAS users, geeks and developers an elegant browser start page. The purpose is stated in the feature list as a multi-device unified entry point, aggregating the sites you use, the internal network services and your tools on one dashboard. The distinction from a bookmark service is that it sits next to the machine whose services it links to. That is why the file transfer helper, the music player, the Docker management panel and the system monitor are all built in rather than bolted on. The resource claim is worth noting precisely: the README says the NAS side uses about 100MB of memory and the client side uses under 80MB of real memory, which is a reasonable claim for a page that also plays local music and shows container state.

## The widget set, and the local music player in it

The widget list is long enough to show what the author thought a personal dashboard needed. The file transfer helper sends text, files and images between devices, supports resumable transfers and large uploads, and has a dedicated image view that sorts and previews image files automatically. The bookmark widget supports custom icons and auto-fills ten common sites such as GitHub and Bilibili on first start. There is a clock and weather widget, an AMap map widget showing your position and navigation, a todo list, an RSS reader, a trending list pulling in Weibo hot search and news rankings, a calculator, and a music player built on MiniPlayer that plays local music files from the server. Docker management can view, start, stop and restart containers and upgrade images. A system monitor shows CPU, memory, disk and network. There is an iframe widget for embedding external pages, a custom HTML widget, and a music component from a third-party service. The icon library is the author's own and holds 60,000 icons, which is the kind of detail that separates a finished dashboard from a demo.

## Everything is configurable, including CSS and JavaScript you inject yourself

The customisation section is where the flexibility claim gets tested. You can add custom components as HTML, custom CSS, custom JavaScript and custom HTML blocks, add a weather widget, upload your own icon images with hex colour codes for the icon background, set a custom wallpaper, and set a group background so that all the cards in a group share one image, blur or mask. There is a visitor counter in the footer showing total visits, today's visits and the current online duration, which you enable in settings. The global custom CSS feature is the interesting one, because it includes a small extension language of its own. You write tags that are converted into media queries for you, with a mobile tag that applies only under a max-width of 768 pixels, a desktop tag for a min-width of 769, and dark and light tags for the two colour modes. The custom JavaScript runs in a sandbox and gets a ctx object for talking to the system, and enabling it requires agreeing to a security disclaimer, which is a sensible thing to ask for.

## Installing on Debian with one script, then a management menu

The recommended path for Debian and Ubuntu needs no Docker at all, because the script downloads the latest release and completes the deployment.

```bash
wget -O deploy_debian.sh https://raw.githubusercontent.com/Garry-QD/FlatNas/main/deploy_debian.sh
chmod +x deploy_debian.sh
sudo ./deploy_debian.sh
```

A separate management script handles the routine operations afterwards, including viewing service status, changing the port, configuring HTTPS, reading logs and uninstalling.

```bash
wget -O manage.sh https://raw.githubusercontent.com/Garry-QD/FlatNas/main/manage.sh
chmod +x manage.sh
sudo ./manage.sh
```

The menu covers viewing the front end and back end ports and the HTTPS status, changing both ports and restarting, writing a certificate and updating the Nginx configuration, following the logs live, restarting Nginx and FlatNas, and a full uninstall that removes the application, its configuration and its logs. If you would rather run the release package directly, you download the flatnas-amd64.zip or flatnas-arm64.zip for your architecture, unpack it somewhere such as /opt/flatnas, and start the binary.

```bash
cd /opt/flatnas
chmod +x flatnas-server
./flatnas-server
```

The address is then the server IP on port 3000.

## The Docker route, and what the socket mount gives you

There is a Docker CLI deployment and a Compose file, and both mount the Docker socket.

```bash
docker run -d \
  -p 23000:3000 \
  -v $(pwd)/data:/app/server/data \
  -v $(pwd)/doc:/app/server/doc \
  -v $(pwd)/music:/app/server/music \
  -v $(pwd)/PC:/app/server/PC \
  -v $(pwd)/APP:/app/server/APP \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name flatnas \
  qdnas/flatnas:latest
```

The volumes map the data directory, the file transfer area, the music folder, the desktop and mobile wallpaper directories, and the socket. The socket mount is the one to think about. It is what makes the Docker management widget possible, since the widget needs to list and control containers, and it is also the standard way to grant a container control over the host Docker daemon, which is about as much privilege as a container can have. If the Docker widget is not something you want, that volume mapping is the thing to drop. The Compose file adds a HOST and PORT environment pair and a BASE_PATH setting for sub-path deployments, and the README notes that the backend can identify a sub-path by itself if you enable it.

## Smart LAN and WAN detection, and the proxy layer

The feature that is most useful on a NAS is the automatic switch between internal and external addresses. The backend identifies the network environment from three dimensions, the client IP, the access domain and the network latency, to decide whether the user is on the LAN or the internet. When it detects the LAN it prefers the configured internal address, and on the public network it switches to the external one, so clicking the same icon always lands on the right place with no manual intervention. The README also lists the deployment shapes it is meant to cope with, including DDNS and direct public access, Nginx reverse proxying, Cloudflare proxy or Tunnel, FRP style tunnelling, sub-path deployment such as /flatnas/, and split front end and back end deployment, with a separate document covering them. The proxy configuration lets the backend forward requests, which solves the problem of internal services that cannot reach external resources, and it is set with a PROXY_URL environment variable supporting http, https, socks5 and socks5h. The proxy status endpoint at /api/config/proxy-status is the first place to look when the proxy toggle does not appear.

## Conclusion

FlatNas fits a NAS or home lab owner who wants one page holding their internal services, downloads and system state, and who is happy to run the whole thing on their own hardware. It does not fit a team that wants a hosted product with a support contract, and the AGPL licence is the first thing to check if you intend to modify it and offer the result as a service. Verify first that the default admin password is changed, that the Docker socket mount is acceptable given the component that controls containers, and that your network topology is one the smart LAN and WAN detection can handle, since a wrong answer there sends every link to the wrong address.

## FAQ

### What is FlatNas and who is it for?

It is a lightweight, highly customisable personal navigation page and dashboard system built with Vue 3 and Go with Gin, intended to give NAS users, geeks and developers an elegant browser start page. It aggregates the sites you use, internal network services and your tools on one dashboard, and the README says the NAS side uses about 100MB of memory while the client side uses under 80MB.

### How do I install FlatNas on Debian or Ubuntu?

The one-command path needs no Docker: download deploy_debian.sh, make it executable and run it with sudo, and it downloads the latest release and completes the deployment. A separate manage.sh script then handles status, port changes, HTTPS configuration, logs, restarts and uninstall.

### Where does FlatNas store its data, and what is the default password?

All configuration, including layout, widgets and bookmarks, is stored in a local data.json file under the server data directory, so the data stays on your own machine. The initial password is admin, and the README asks you to change it in the settings after logging in.

### What does the Docker deployment mount into the container?

It maps the data, doc, music, PC and APP directories from the host into the container, and it mounts /var/run/docker.sock so the built-in Docker management widget can list and control containers. The socket mount is the part to consider carefully, since it grants the container control of the host Docker daemon.

## Sources

- [Garry-QD/FlatNas on GitHub](https://github.com/Garry-QD/FlatNas)
- [License: AGPL-3.0](https://github.com/Garry-QD/FlatNas/blob/main/LICENSE)
- [Project website](https://flatnas.top/)
- [README](https://github.com/Garry-QD/FlatNas/blob/main/README.md)
- [Releases](https://github.com/Garry-QD/FlatNas/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/garry-qd-flatnas