The smallest reliable Uptime Kuma deployment is a four-line Docker Compose service: use the louislam/uptime-kuma:2 image, keep the container restarting unless you stop it, persist /app/data, and publish port 3001. Save the file below as compose.yaml, create its data directory, start it with Docker Compose, and open http://HOSTNAME-OR-IP:3001.
Antihost offers Linux VPS plans with full root access, unlimited traffic on a 1 Gbps port and a 14-day free trial.
Use this compose.yaml
Create a new directory for the instance and save the following as compose.yaml. This mirrors the current minimal example published in the Uptime Kuma project repository.
As an Amazon Associate I earn from qualifying purchases.
services:
uptime-kuma:
image: louislam/uptime-kuma:2
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
- "3001:3001"The left side of the port mapping is the port on the Docker host; the right side is the port inside the container. The application listens on container port 3001, so the default browser address uses host port 3001 as well.
Prerequisites and directory layout
You need a machine that can run Docker Engine and the Docker Compose plugin. The commands below use the current docker compose syntax (with a space), not the older standalone docker-compose command.
#1 Best Overall
- BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
- EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
- COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
- LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
- WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
Choose a directory that will remain on the host. The relative bind mount in the example is resolved from that directory, so running Compose from somewhere else changes where the data is stored.
mkdir uptime-kuma
cd uptime-kuma
mkdir dataAfter these commands, the expected layout is:
uptime-kuma/
├── compose.yaml
└── data/Do not place the Compose file in a temporary directory if you expect to manage the instance over time. Keeping the file and data directory together makes upgrades, backups, and recovery easier to understand.
Start Uptime Kuma and verify the container
- From the directory containing
compose.yaml, start the service in the background:docker compose up -d - Check the service state:
docker compose psThe service should be listed as running. A container that exits immediately needs log inspection before you try the browser again.
- Follow the startup log while the application initializes:
docker compose logs -f uptime-kumaPress
Ctrl+Cto stop following logs; this does not stop the container. - From a machine that can reach the host, browse to
http://HOSTNAME-OR-IP:3001. ReplaceHOSTNAME-OR-IPwith the server’s DNS name or IP address.
The first page should allow you to complete Uptime Kuma’s initial setup. If the browser cannot connect, work through the troubleshooting order later in this guide rather than deleting the container or data directory.
What each Compose setting does
| Setting | Value in the example | Purpose |
|---|---|---|
| Service name | uptime-kuma |
Names the Compose service and is used by commands such as docker compose logs -f uptime-kuma. |
| Image | louislam/uptime-kuma:2 |
Uses the current major-version 2 image line shown in the project’s repository example. |
| Restart policy | unless-stopped |
Restarts the service after a failure or host reboot, but respects an intentional stop. |
| Volume | ./data:/app/data |
Stores the application’s database, settings, and monitor configuration in the host’s data directory. |
| Ports | 3001:3001 |
Publishes host port 3001 to the application’s internal port 3001. |
The official minimal file intentionally does not set container_name, environment variables, a custom network, or a healthcheck. Compose can support those keys, but adding them is a deployment decision, not a requirement for a working local installation.
Persistence: why the data mount matters
Containers are replaceable. If you recreate a container without a persistent mount, the instance state inside that container can disappear with it. The ./data:/app/data mapping keeps Uptime Kuma’s database, settings, and monitor definitions outside the container lifecycle.
Keep the host directory when recreating
Commands such as docker compose down followed by docker compose up -d can recreate the container while retaining the bind-mounted files. Do not remove the data directory unless you deliberately want to discard the instance state. Deleting the directory is not a routine reset or upgrade step.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #2
- WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
- AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
- PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
- ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
- COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
Bind mount versus a named volume
The repository example uses a bind mount because the files are visible at a predictable path beside the Compose file. Docker also supports a managed named volume. The choice changes where you inspect and back up the files, not the container path Uptime Kuma uses.
| Option | Compose declaration | Practical characteristics |
|---|---|---|
| Bind mount | ./data:/app/data |
Files live in the project directory on the host. This is the official minimal example and is straightforward to copy or archive. |
| Named volume | uptime-kuma-data:/app/data plus a top-level volumes: declaration |
Docker manages the storage location. It avoids tying the data path to the Compose directory, but you need Docker volume commands or a backup procedure that can access the volume. |
If you change from a bind mount to a named volume, that is a storage migration, not a cosmetic edit. Copy the existing data into the new volume before switching if you need to preserve the current instance.
Filesystem locking is a database requirement
Uptime Kuma’s installation guidance states: “Filesystem support for POSIX file locks is required to avoid SQLite database corruption.” The project also warns about file-locking problems on unsuitable network filesystems. A local host directory or a Docker-managed local volume is the conservative choice.
If the Docker host stores data on a NAS or another network filesystem, verify that it provides reliable POSIX locking before using it for the SQLite database. A mount that permits ordinary reads and writes can still be unsafe if lock operations are incomplete or unreliable. Database locking errors or corruption symptoms are a reason to move the data to storage with proper lock support, not to repeatedly restart the container.
Choosing a host port
Port 3001 is the documented internal and default published port. If another process already occupies host port 3001, change only the number on the left:
services:
uptime-kuma:
image: louislam/uptime-kuma:2
restart: unless-stopped
volumes:
- ./data:/app/data
ports:
- "8080:3001"Apply the change with docker compose up -d, then use http://HOSTNAME-OR-IP:8080. The container still listens on port 3001; only the host-facing entry point changed.
Rank #3
- Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
- Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
- Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
- ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
- Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
Common port-mapping mistakes
- Browsing to port 3001 after changing the host side to 8080.
- Changing the right side and assuming the application will automatically move its listening port. The documented container port remains 3001.
- Testing with
localhostfrom a different computer. In that case,localhostrefers to the computer running the browser, not the Docker host. - Forgetting that a host firewall or cloud security rule may need to allow the selected host port.
Image tags, versions, and upgrades
The current repository example uses the major tag louislam/uptime-kuma:2. An older version 1 installation page documents louislam/uptime-kuma:1 as its recommended stable tag and describes nightly tags as development builds. These references belong to different major-version lines.
Do not mix major-version instructions
Keep the image tag aligned with the instance you already operate. Do not apply version 1 migration advice casually to a version 2 deployment, or assume that changing the tag is a harmless point update. Before a major-version change, read the project’s migration notes and make a recoverable backup of the data directory.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Routine image refresh
For a normal refresh within the selected major line:
- Back up the
datadirectory (or your named volume) while the instance is in a state you can restore. - Pull the image referenced by the Compose file:
docker compose pull - Recreate the service with the pulled image:
docker compose up -d - Confirm that it is running:
docker compose ps - Review startup output if anything looks different:
docker compose logs -f uptime-kuma
The project sources establish the image tags and persistent path; Docker Compose does not create an automatic backup of your Uptime Kuma data. Treat the backup as an operator responsibility, especially before a major-version migration.
Optional Compose additions
The minimal service is enough for a single host, but Compose supports additional service keys when your environment needs them.
Healthchecks
A healthcheck can expose whether a service responds as expected, which is useful to an orchestrator or monitoring system. The minimal Uptime Kuma example does not declare one, and the project material does not provide a universal healthcheck command here. Do not paste an arbitrary probe and assume it represents application health; choose a check that matches your deployment and test its exit status.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #4
- Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
- Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
- 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
- Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
- USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC
Logging
Compose supports a logging section for controlling Docker’s log driver and options. Configure retention deliberately on hosts with limited disk space. Keep enough history to diagnose startup, permission, and database errors, while avoiding an unbounded log directory.
Networks and reverse proxies
A custom Compose network is useful when a reverse proxy or another container must reach Uptime Kuma by service name. A reverse proxy or TLS terminator can sit in front of the published service, but that is outside the minimal local setup. If you put a proxy in front, the browser URL and external port become the proxy’s values; the container still serves on its internal port 3001.
Environment variables and container names
Environment variables and container_name are supported Compose concepts, but neither is needed by the ready-to-use file. Avoid adding settings simply because they are available: every extra value creates another item to document and troubleshoot.
Troubleshoot an unreachable or failing instance
Use this order so you distinguish a stopped process, a port problem, a filesystem problem, and a database-locking problem.
1. Confirm the service state
docker compose psIf the service is not running, inspect the exit status and continue with the logs. The unless-stopped policy will restart many failures, but repeated restarts do not explain the underlying error.
2. Read the service logs
docker compose logs -f uptime-kumaLook for image startup failures, permission errors under /app/data, or database messages. Stop following with Ctrl+C when you have captured the relevant lines.
Best Value
- Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
- Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
- Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
- Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
- Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.
3. Verify the URL uses the host side
For 3001:3001, browse to port 3001. For 8080:3001, browse to port 8080. The number in the browser must match the left side of the mapping, and the hostname must resolve to the Docker host.
4. Check the data path and permissions
Confirm that the data directory exists beside compose.yaml and that the container can write to it. A read-only mount, an inaccessible parent directory, or ownership that blocks the container can prevent startup or stop configuration from being saved. Correct the host filesystem permissions according to your operating system and Docker setup, then run docker compose up -d again.
Free tools Windows power users keep installed
One-click scans. No signup required.
5. Investigate locking and corruption symptoms
If logs report SQLite locking or corruption, first stop making repeated writes to the same database. Verify where ./data resolves and whether that path is on a network filesystem. Move the mount to storage with reliable POSIX file-lock support, restore a known-good backup if available, and then start the service. The project’s warning about POSIX locks is a data-safety requirement, not an optional performance tweak.
6. Recheck after a configuration change
After changing a port, mount, or image tag, apply the file with docker compose up -d, run docker compose ps, and inspect logs again. This confirms that Compose recreated the service from the file you actually edited.
Operational checklist
- Keep
compose.yamland its intendeddatalocation documented. - Use
louislam/uptime-kuma:2for a new deployment based on the current repository example, unless you have a deliberate compatibility reason to stay on another major line. - Back up the data before image upgrades and before any major-version migration.
- Never remove
dataduring ordinary recreation. - Use local storage or a Docker local volume unless your network filesystem demonstrably supports the required POSIX locks.
- Record the host port if it differs from 3001 so operators use the correct URL.
- Keep optional networks, logging, healthchecks, and proxy configuration separate from the minimal baseline until they solve a specific deployment need.
Minimal setup versus deployment variants
| Decision | Baseline in this guide | When to choose another variant |
|---|---|---|
| Storage | Bind mount ./data:/app/data |
Use a named volume when Docker-managed storage fits your backup and administration model; migrate existing files before switching. |
| Host port | 3001 |
Use another free host port when 3001 is occupied; keep the container side at 3001. |
| Image line | louislam/uptime-kuma:2 |
Stay on a different major line only for a known compatibility requirement and follow that line’s migration guidance. |
| Filesystem | Local directory or Docker local volume | Use network storage only after verifying reliable POSIX file locking. |
| Access | Direct HTTP publication from Docker | Add a reverse proxy or TLS terminator when your wider deployment requires it. |
| Compose features | Service, restart policy, volume, and port | Add healthchecks, logging, networks, or environment variables for a documented operational need. |
What a successful result looks like
A successful installation has a running uptime-kuma service in docker compose ps, startup logs without fatal errors, and a browser connection through the selected host port. The monitor configuration and settings remain present after a container recreation because they live under the host-backed data path. If those conditions are not met, the failure is usually identifiable by checking the service state, logs, port side, data-directory writability, and filesystem locking in that order.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errors
