Both of you are looking at real data and reaching different conclusions, because you’re each seeing a different segment of the same path. The client’s experience includes a leg you can’t see from your side, and your metrics cover a leg they can’t see from theirs.

That missing segment is usually the last mile, and being able to explain it convincingly matters as much as diagnosing it. A client who feels they’re being deflected won’t accept a technically correct answer.

What “last mile” actually means in a China routing context

Think of the path in two halves. The international leg carries traffic from your server to the point where it enters Chinese domestic carrier infrastructure, and that’s the segment a premium route like CTGNet, CUP, or CMIN2 exists to optimize.

The last mile is everything after that: the domestic hops from the carrier’s border network through provincial infrastructure to the client’s actual connection, whether that’s a fixed broadband line or a mobile tower. It’s typically a small number of hops, and it’s entirely inside networks that no foreign host has any commercial relationship with.

This is why a route can be genuinely excellent and still deliver a poor experience. The two halves fail independently, and optimizing one does nothing for the other. A clean international leg into a congested provincial network produces exactly the complaint you’re fielding.

Why this gets misattributed to your server

From the client’s side, the only variable they can see is your service. They open the app, it’s slow, and the app is the thing you’re responsible for. The inference is reasonable even though it’s wrong.

It’s also reinforced by the fact that other things work fine for them. Domestic Chinese services feel fast because their traffic never leaves the country, skipping the international leg and the border handoff entirely. That contrast makes your service look uniquely broken, when the real difference is that domestic traffic isn’t making the same journey at all.

The asymmetry in available evidence compounds it. You have server metrics, and they have lived experience, and neither of those datasets contains the hop where the problem lives. This is why the conversation tends to stall until someone produces a traceroute.

How to actually explain this without sounding like you’re deflecting blame

The single most effective move is to stop describing and start showing. Run an MTR from a public Looking Glass toward their network, or ask them to run one toward your server, and look at the output together. Point at the specific hop where latency jumps or loss appears.

Then narrate it in plain terms rather than protocol language. Something like: “Traffic leaves our server and stays on China Telecom’s premium backbone for most of the trip, and you can see the latency staying flat through those hops. Here, at hop eleven, it enters the provincial network that serves your building, and that’s where it jumps from 60 milliseconds to 210. Everything before that is ours, and it’s clean. That hop isn’t something any host outside China can route around.”

Say what you can’t control, explicitly. Counterintuitively, this builds more confidence than hedging does, because a technically capable client can tell the difference between an honest boundary and an excuse. Claiming you’ll “look into optimizing the route” when the bottleneck is inside a Chinese provincial network sets up a follow-up conversation where you have nothing new to report.

Finally, avoid the temptation to end there. “It’s the last mile, nothing we can do” is accurate and unsatisfying, and there are usually two or three real checks left to run.

What can still be done about last-mile issues

The most common fixable cause hiding behind a last-mile complaint is a carrier mismatch. Ask which carrier the client is actually on, China Telecom, China Unicom, or China Mobile, and confirm your route is optimized for that specific one. If they can give you their IP address, a whois lookup on it returns the AS number that announces the prefix, and PeeringDB will tell you which network that AS belongs to. A server with an excellent China Telecom path serving a China Unicom user is a genuinely suboptimal setup, and it’s fixable rather than a fact of life.

Second, test across the day. Domestic congestion inside China varies substantially between off-peak and business hours, and a complaint that only appears between 8pm and 11pm local time is a congestion pattern rather than a routing defect. Establishing that with timestamped data also reframes the conversation productively: you’re now discussing predictable variance instead of an unexplained failure.

Third, look at what your application does under high latency. An app making twenty sequential requests where five would do will feel dramatically worse on a high-latency path than on a local one, and that part genuinely is yours to improve. Reducing round trips, enabling connection reuse, and moving static assets closer to users all mitigate a last mile you can’t fix directly.

It’s also worth setting expectations about verification itself. A Looking Glass reading reflects one moment, not a guaranteed daily average, which is the same reason it pays to ask pointed questions of any provider rather than treating one good test as a promise.

A short script for the conversation

If it helps, the structure that tends to work is: acknowledge, show, delineate, then act. Acknowledge that what they’re experiencing is real rather than opening with your metrics. Show the traceroute and point at the hop. Delineate which segment is yours and which isn’t, without softening it. Then name the specific things you will check, the carrier match, the time-of-day pattern, and your application’s round-trip behavior.

What that sequence avoids is the failure mode where the client hears “not our problem” as the first substantive statement. The technical content is identical; the order changes whether it lands as diagnosis or as deflection.

Wrapping up

Last-mile congestion inside China’s domestic networks is a real and common cause of complaints that arrive pointed at your server. It’s also genuinely outside the reach of any host operating from outside the country.

The fastest path through the conversation isn’t defending your infrastructure. It’s showing the client exactly where in the path the time is going, being straightforward about which parts you own, and following up on the handful of checks, carrier match, timing pattern, and application round trips, that actually are yours.

Thanks for reading! Whether you’re walking a client through a traceroute or working out which hops are genuinely yours to fix, knowing where your control ends saves a lot of wasted effort. If you’re looking for China routing you can verify yourself rather than take on faith, Riven Cloud runs KVM VPS in Tokyo and Singapore with all three named premium paths on every plan: CTGNet on China Telecom, CUP on China Unicom, and CMIN2 on China Mobile, each testable through a public Looking Glass before you buy.

Ready to see the numbers for your own traffic? Deploy a server or contact our team with questions.

Frequently asked questions about last-mile China routing

What’s the difference between the international leg and the last mile?

The international leg runs from your server to the point where traffic enters Chinese carrier infrastructure, and that’s what a premium route optimizes. The last mile covers the domestic hops from there to the user’s own connection, inside networks a foreign host has no relationship with.

How do I know if a slowdown is happening in the last mile?

Run a sustained MTR and look at where latency climbs or loss appears. If the international hops stay flat and the jump happens in the final few hops nearest the user, that localizes it to the domestic segment.

Can a mismatched carrier cause what looks like a last-mile problem?

Yes, and it’s the most common fixable cause. A route optimized for China Telecom serving a user on China Unicom will underperform even when both networks are healthy, because the premium path isn’t the one carrying that user’s traffic.

Does peak-hour timing affect last-mile congestion?

Substantially. Domestic congestion in China varies a lot by time of day, so a test at 3am can look completely different from the same test during evening peak. Testing at multiple times is what separates a congestion pattern from a routing defect.

Is there anything that can actually be done about last-mile issues?

Nothing directly, since those hops sit inside Chinese domestic networks. What you can control is the international leg: confirming it runs on the premium path for your client’s specific carrier, and using a traceroute to localize where the problem actually sits before assuming it’s yours.

Should I just tell a client there’s nothing we can do?

That’s accurate but incomplete, and it usually damages trust. Walk through the traceroute with them, be clear about the boundary, and then name the checks that are genuinely yours: carrier match, time-of-day pattern, and how many round trips your application needs per page load.

They aren’t. They govern different things, attach to different parties, and are triggered by different decisions. One is about verifying who your users are. The other is about whether you’re allowed to serve a site from inside mainland China at all.

Getting the distinction right matters because it changes the answer to the only question most businesses actually care about: does any of this reach a server in Tokyo or Singapore that happens to have Chinese visitors.

The short version

What real-name registration actually is

Real-name registration is China’s requirement that users of domestic internet services be identified with verified real-world identity, typically a national ID number or a mobile number already tied to one. It covers mobile SIM cards, accounts on domestic platforms like WeChat and Weibo, apps distributed through Chinese app stores, and domestic hosting accounts.

It’s rooted in China’s Cybersecurity Law, whose Article 24 requires network operators to obtain real identity information when signing service agreements with users, and to refuse service where that information isn’t provided. Enforcement runs through the platforms and telecom carriers themselves, which are the parties held responsible.

The key structural point is that it’s an obligation on the operator of a domestic service, not a rule that attaches to users wherever they happen to browse. It has tightened steadily rather than loosened, so if you’re planning multi-year, assume more verification rather than less.

What ICP filing and an ICP license actually are

ICP is where most of the confusion lives, partly because there are two distinct things sharing the abbreviation.

An ICP filing, usually called by its Chinese name beian, is the registration required for any site served from mainland Chinese infrastructure. It’s free, and it requires a mainland-registered entity, though a wholly foreign-owned enterprise generally qualifies. Enforcement is delegated to the hosting providers: a mainland host is required to verify your filing before serving your site, and to suspend sites that lack one.

A commercial ICP license, the ICP证, sits on top of that and is required when the service generates revenue online rather than simply publishing information. It involves substantive review rather than a registration formality, takes considerably longer, and carries an ownership constraint covered below that catches a lot of foreign businesses off guard.

The trigger for both is infrastructure, not audience. Filing is tied to hosting on mainland servers, which is why a site hosted in Tokyo, Singapore, or Hong Kong doesn’t need one. It’s worth being precise here: such a site isn’t merely exempt, it generally can’t obtain a filing at all, because the filing presupposes mainland hosting.

How the two connect

Here’s the relationship that makes the comparison useful rather than academic: the ICP path is what converts real-name obligations from something you inherit to something you carry.

A foreign-hosted business encounters real-name verification indirectly, through the platforms it builds on. Offer WeChat login and you’re consuming an identity system that already performed verification, bound by WeChat’s terms about what you do with the result. Use a China-based SMS gateway, accept Alipay or WeChat Pay, or distribute through a Chinese app store, and each of those relationships brings its own filing and identity expectations. Your compliance surface tracks your integrations, not your server location.

Take an ICP filing and a mainland entity, and the position changes in kind rather than degree. You’re now a domestic operator inside the regulatory perimeter, where the identity framework applies to you directly, alongside content responsibilities and ongoing filing duties that an offshore service never touches. That’s the real reason ICP is a strategic decision rather than a procedural step.

The ownership constraint that decides it for many businesses

The commercial ICP license carries a restriction that reframes the whole question for foreign companies: it’s generally limited to wholly Chinese companies or joint ventures with no more than 50% foreign ownership.

For a foreign-majority business, that means the commercial license usually isn’t a matter of budget or patience. It requires restructuring, typically a joint venture with a Chinese partner holding at least half the equity, which is a corporate decision rather than a compliance task.

This is why the practical comparison for most foreign businesses isn’t “real-name registration or ICP license.” It’s “operate offshore and reach China over optimized routing, or restructure the company to operate inside it.” Framed that way, the latency conversation that usually dominates these discussions turns out to be the smaller half of the decision.

Which question you’re actually answering

If your infrastructure sits outside mainland China, neither ICP requirement applies to you, and real-name registration reaches you only through the domestic platforms you’ve chosen to integrate with. The hosting and routing layer is a network decision. A VPS in Tokyo or Singapore reaching mainland users over CTGNet, CUP, or CMIN2 doesn’t make you a domestic operator, and choosing a premium carrier path doesn’t move you one step closer to the licensing regime.

One caveat worth raising with a partner rather than assuming: if you add mainland CDN or cloud capacity to an offshore deployment, you’ve introduced mainland infrastructure into the picture, and the filing question deserves a direct answer from that provider rather than an inference from your own setup.

Beyond that, the useful exercise is listing the domestic Chinese services you actually depend on, payment processors, login providers, SMS gateways, app store distribution, CDN partners, and getting advice on that list. “Does Chinese internet law apply to us” has no useful answer. “What do we take on by using this payment processor and this SMS gateway, with no Chinese entity” has a real one, and a China-focused advisor can usually give it quickly.

Wrapping up

Real-name registration governs identity verification by operators of domestic services. ICP filing governs whether you may serve a site from mainland infrastructure at all, and the commercial license governs whether you may charge for it. They’re separate rules, and only the ICP path pulls a business into the perimeter where the identity rules apply to it directly.

For a foreign-hosted service, the honest summary is that neither applies to your server, and the exposure you do have arrives through the domestic platforms you’ve integrated with. If the ICP route is ever genuinely on the table, the ownership constraint on the commercial license is the detail to check first, because it decides the question more often than latency does.

Thanks for reading! Whether you’re weighing a mainland presence or planning to serve China from outside it, knowing which of these two rules actually applies to you is what keeps the decision straightforward. If you’re looking for China routing you can verify yourself rather than take on faith, Riven Cloud runs KVM VPS in Tokyo and Singapore with all three named premium paths on every plan: CTGNet on China Telecom, CUP on China Unicom, and CMIN2 on China Mobile, each testable through a public Looking Glass before you buy.

Ready to see the numbers for your own traffic? Deploy a server or contact our team with questions.

Frequently asked questions about real-name registration and ICP licensing

What’s the core difference between real-name registration and an ICP license?

Real-name registration governs verifying the identity of users on a domestic service. ICP filing and licensing govern whether you’re permitted to serve a site from mainland infrastructure, and whether you may charge for it. Different obligations, different triggering conditions.

Does my foreign-hosted server need an ICP filing to reach Chinese users?

No. The filing is tied to hosting on mainland Chinese infrastructure rather than to your audience, so a site hosted in Tokyo or Singapore doesn’t need one and generally can’t obtain one either.

Does real-name registration apply to my foreign-hosted service directly?

No. It attaches to operators of domestic services under Chinese jurisdiction. Where it reaches a foreign business, it’s through the terms of domestic platforms you’ve integrated with, such as WeChat login or a China-based SMS gateway.

What’s the difference between an ICP filing and a commercial ICP license?

The filing is a free registration required for any mainland-hosted site, and a wholly foreign-owned entity can generally obtain it. The commercial license is an additional approval for revenue-generating online services, involving substantive review and a much longer timeline.

Can a foreign-owned company get a commercial ICP license?

Usually not on its own. The commercial license is generally limited to Chinese companies or joint ventures where foreign ownership doesn’t exceed 50%, so it typically requires restructuring rather than just an application.

Does adding a mainland CDN to an offshore setup change anything?

Potentially, because you’ve introduced mainland infrastructure into the delivery path. It’s worth putting that question directly to the CDN provider rather than assuming your offshore hosting settles it.

Should I get advice on my specific integrations?

Yes, and it’s far more productive than the general question. List the domestic services you depend on, payment, login, SMS, app store, CDN, and ask about that list, since obligations vary by platform rather than applying uniformly.

It’s worth being direct about this one: for most foreign-hosted setups, it changes nothing about your route. But it does change something real about China’s domestic infrastructure, and there’s one specific scenario where that reaches you.

This piece covers what the initiative actually is, why Beijing launched it, and the narrow set of circumstances under which it becomes your problem rather than background reading.

What Eastern Data and Western Computing actually is

Eastern Data and Western Computing (东数西算) is a national Chinese strategy approved in February 2022 by the National Development and Reform Commission and three other central departments. The premise is in the name: data generated in the developed eastern coastal regions gets processed in new data center capacity built in the western and inland provinces.

The build-out is organized into eight national computing hubs and ten data center clusters. Four of those hubs sit in the developed regions the name refers to as “east”: Beijing-Tianjin-Hebei, the Yangtze River Delta, the Guangdong-Hong Kong-Macao Greater Bay Area, and the Chengdu-Chongqing economic circle. The other four are the western ones: Inner Mongolia, Guizhou, Gansu, and Ningxia.

That split is the detail most summaries drop, and it changes how the policy should be read. This was never a plan to move all compute west; it’s a plan to keep latency-sensitive workloads near the eastern population centers while directing the growth in less time-critical processing, training runs, batch jobs, cold storage, toward cheaper western capacity.

The reasoning is practical rather than ideological. Land and electricity are cheaper in the west, hydro and wind generation capacity is more abundant there, and the eastern grid was under genuine strain from data center demand concentrated around major coastal cities. Moving compute west addresses a power problem and a regional development goal at the same time.

What this does, and what it doesn’t

This is a policy about where China builds domestic compute and storage. It is not a policy about how international traffic enters China.

The things that actually determine your route quality sit entirely outside its scope: the international gateway points where foreign traffic crosses into Chinese networks, the peering arrangements the three state carriers maintain with networks abroad, and the specific premium paths like CTGNet, CUP, and CMIN2 that traffic rides once it’s in. None of those change because a data center opened in Guizhou.

A server in Tokyo or Singapore reaching mainland China crosses the same borders on the same carrier infrastructure it did before the initiative started. If your setup is a foreign-hosted VPS serving Chinese users over a premium carrier route, this policy is context rather than a variable.

Where it’s actually relevant to a foreign business

There’s one scenario where it genuinely reaches you, and it’s a common enough architecture to be worth naming: a hybrid setup where you pair foreign-hosted infrastructure with a domestic Chinese CDN or cloud partner handling caching or compute inside the country.

In that arrangement, where your partner’s infrastructure physically sits is now a live variable. A workload that used to run near Shanghai or Shenzhen might increasingly run out of a western hub instead, and that adds domestic distance between the compute and your users, who remain heavily concentrated in the eastern population centers. Your international route didn’t change, but the last leg of the journey did.

The practical response is simply to ask. Domestic providers can usually tell you which region serves a given workload, and if the answer is a western hub while your users are in Shanghai, that’s a conversation worth having about placement options rather than something to discover from a latency graph.

Why this comes up in “why not just host inside China” conversations

The other place this initiative shows up is in internal discussions where someone asks why the company doesn’t simply host inside mainland China, given how much capacity is clearly being built there.

The honest answer has little to do with capacity. Operating a public-facing service from inside mainland China requires an ICP license, which requires a Chinese business entity, which brings a set of ongoing regulatory obligations that a foreign company usually hasn’t budgeted for in either time or legal cost. That barrier is unchanged by Eastern Data and Western Computing, which is a domestic build-out program rather than a liberalization of who can operate infrastructure there.

So the initiative is useful evidence that China is investing heavily in domestic capacity, and it’s simply not evidence that the licensing path got easier. Those are separate questions, and conflating them tends to produce a plan that stalls at the legal review stage.

Does this change anything for a foreign-facing server?

For a straightforward foreign-hosted deployment, no. Your traffic enters China at the same gateways, on the same carrier paths, with the same peak-hour congestion characteristics as before. The hub structure reinforces this: because the eastern hubs exist precisely to keep latency-sensitive workloads close to users, the capacity being built out west is largely the kind that was never going to sit in your request path anyway.

For a hybrid deployment with a domestic partner, possibly yes, and the way to find out is to ask that partner which hub serves your workload. Latency to that specific component will corroborate the answer, since a placement shift is measurable rather than theoretical, but asking is considerably faster than reverse-engineering it from a graph.

Either way, the part of the path you actually control, from your server to China’s border, is best verified the same way it always was. A public Looking Glass reading tells you what your route looks like right now, which is more useful than reasoning about policy documents.

Wrapping up

Eastern Data and Western Computing is a real and significant shift in where China builds its own data infrastructure. It’s a domestic capacity story, not an international routing story, and treating it as the latter leads to worrying about the wrong variable.

For most foreign-facing businesses reaching China over a premium carrier path, this is context worth understanding and not a factor that changes your routing decisions. If you run a hybrid setup with a domestic partner, the one question worth asking is where their compute actually sits.

Thanks for reading! Whether you’re following how China’s data center map is shifting or simply routing traffic back to players and customers there, the carrier path matters more than which province a facility happens to sit in. If you’re looking for China routing you can verify yourself rather than take on faith, Riven Cloud runs KVM VPS in Tokyo and Singapore with all three named premium paths on every plan: CTGNet on China Telecom, CUP on China Unicom, and CMIN2 on China Mobile, each testable through a public Looking Glass before you buy.

Ready to see the numbers for your own traffic? Deploy a server or contact our team with questions.

Frequently asked questions about Eastern Data and Western Computing

Does Eastern Data and Western Computing affect how fast my China-optimized route performs?

Not directly. It governs where China builds domestic compute capacity, not the international carrier paths like CTGNet, CUP, or CMIN2 that a foreign-hosted server uses to reach Chinese users. Your route crosses the same gateways it always did.

Do I need to do anything differently because of this policy?

Only if you use a domestic Chinese CDN or cloud partner alongside your own infrastructure. In that case, confirm which regional hub serves your workload, since western placement adds domestic distance to users concentrated in eastern cities.

Is this related to China’s Great Firewall or internet censorship?

No. It’s a data center and energy policy aimed at grid load and regional development. Content filtering and international gateway control are governed separately and weren’t changed by this initiative.

Why did China launch this initiative in the first place?

Primarily to relieve an eastern power grid under pressure from concentrated data center demand, and to use cheaper land and more abundant renewable generation in the west. Regional economic development in inland provinces was the other stated goal.

Does this mean data centers in eastern Chinese cities are being phased out?

No. The policy directs new capacity growth westward rather than decommissioning existing eastern facilities, which continue to serve latency-sensitive workloads close to the population centers.

Can a foreign company use one of these new western hubs?

Renting capacity from a Chinese provider is possible, but operating a public-facing service from inside mainland China requires an ICP license and a Chinese business entity, and that requirement is the same regardless of which region the facility sits in. The new capacity doesn’t change the licensing path.

For business traffic, it usually makes things worse. Not marginally worse either: adding a VPN hop to a China-facing production path frequently increases latency, adds packet loss, and introduces a failure mode that’s harder to diagnose than the problem it was meant to solve.

The reason comes down to a mismatch between what a VPN is built for and what a business needs, so it’s worth walking through what actually happens to your traffic.

Why people reach for a VPN in the first place

For an individual inside China trying to reach a blocked site, a VPN does something genuinely useful. It wraps traffic in an encrypted tunnel to a server outside the country, and the content filtering that would have blocked the destination can’t read what’s inside the tunnel.

That mental model gets carried into a different problem without much examination. Serving a service reliably to users inside China is not the same task as one person occasionally reaching a blocked website from inside China, and the tool that solves the second one isn’t designed for the first.

The distinction matters because the two use cases have opposite tolerances. A person circumventing a block will accept slow and unreliable, because slow beats blocked. A business serving thousands of users needs consistent and predictable, which is precisely what a VPN hop erodes.

What a VPN actually does to your route

Start with geometry. A VPN routes traffic through an intermediate server, which means the packet’s physical path gets longer, not shorter. If your server is in Tokyo, your user is in Shanghai, and the VPN endpoint is in Los Angeles, you’ve added a Pacific crossing in each direction to a route that didn’t need one.

Then there’s the quality of the infrastructure itself. General-purpose VPN providers aren’t buying premium carrier paths into China; they’re running on ordinary transit, often oversubscribed, because their product is measured on server count and price rather than on route quality to one specific country. Traffic that would otherwise ride a premium path like CTGNet, CUP, or CMIN2 instead rides whatever generic transit the VPN provider happens to have.

The third factor is the most consequential, and it works against tunnels from two directions at once. Older, widely deployed VPN protocols have recognizable handshake patterns that filtering infrastructure can match directly. Newer protocols that avoid that by looking like pure random data run into the opposite test: published research on how the Great Firewall identifies fully encrypted traffic found it applies fairly crude heuristics that exempt traffic resembling a recognized protocol and act on much of what’s left, which is exactly where a fully encrypted tunnel sits. The result isn’t a clean tunnel that gets through; it’s a tunnel that intermittently gets throttled, degraded, or reset, specifically because it’s identifiable as a VPN. Your traffic ends up worse off than unremarkable traffic on a good route would have been.

Where this actually bites business traffic

The workloads that suffer most are the ones with no tolerance for variance. API calls with client-side timeouts, database replication that falls behind and then has to catch up, payment callbacks that expect a response inside a fixed window, and real-time features like chat or live updates all degrade visibly when the path underneath them is inconsistent.

It also produces a support problem. When a VPN hop is in the path, intermittent failures come with no clear signal about where they originated, so your team spends time investigating an application that’s working correctly. Removing an unnecessary tunnel often does more for diagnosability than any amount of additional monitoring.

There’s a compounding effect worth naming too. Because the VPN adds latency, every retransmission costs more than it would on a direct route, so the packet loss the VPN introduced is more expensive to recover from than the same loss would have been without it.

When a VPN does make sense

None of this makes VPNs useless in a China context. It makes them the wrong tool for public service delivery.

A site-to-site VPN connecting your own offices or internal infrastructure is a reasonable use: the traffic volume is modest, the participants are known, and a private encrypted link between two of your own locations is exactly what the technology is for. Internal administrative access for your own team falls into the same category, as does an emergency fallback path you keep available but don’t route production traffic through.

The dividing line is whether the traffic belongs to your users or to your own operations. Internal, low-volume, and security-motivated points toward a VPN being fine. Public, continuous, and latency-sensitive points away from it.

What actually helps instead

For business traffic reaching mainland China, the thing that works is carrier-optimized routing that covers the carriers your users are actually on, which for any sizeable user base usually means all three rather than one. Keeping traffic on China Telecom’s, China Unicom’s, or China Mobile’s own premium backbone for a longer stretch of the path removes congested handoffs rather than adding an extra one.

Riven Cloud runs premium paths on all three: CTGNet on China Telecom (AS23764 and AS4809), CUP on China Unicom (AS9929 and AS10099), and CMIN2 on China Mobile (AS58807). Naming them matters because it’s what makes the claim checkable rather than aspirational.

The other half is verification. Every location has a public Looking Glass for ping, traceroute, and BGP lookups, so you can compare a real route against whatever you’re running today before changing anything. One caveat worth stating plainly: a Looking Glass reading reflects a single moment, not a guarantee of day-to-day performance, so test more than once and at more than one time of day.

Wrapping up

A VPN’s strength is getting an individual around a block. It was never designed to deliver consistent, low-latency service to a user base, and in China specifically it’s actively penalized by the filtering it’s meant to evade.

If users in China are having a bad time with your service, the productive move is checking whether your server’s route to their carrier is any good, not wrapping a bad route in a tunnel and hoping the encryption compensates.

Thanks for reading! Whether you’re testing through a tunnel or serving users directly, the carrier path underneath matters more than the software layered on top of it. If you’re looking for China routing you can verify yourself rather than take on faith, Riven Cloud runs KVM VPS in Tokyo and Singapore with all three named premium paths on every plan: CTGNet on China Telecom, CUP on China Unicom, and CMIN2 on China Mobile, each testable through a public Looking Glass before you buy.

Ready to see the numbers for your own traffic? Deploy a server or contact our team with questions.

Frequently asked questions about VPNs and China routing

Does a VPN always make China routing worse?

Not in every configuration, but for business traffic serving users in China it usually does. You’re adding physical distance, riding generic transit instead of a premium carrier path, and running a protocol that border filtering specifically looks for.

Why does China’s border filtering target VPN traffic specifically?

Older VPN protocols carry recognizable handshakes that can be matched directly. Newer ones that look like random data get caught by the inverse test, since traffic resembling no known protocol is itself treated as suspect. Either way the tunnel stands out from ordinary traffic, even when what’s inside it is entirely unremarkable.

Is a business VPN different from a consumer VPN in this context?

The underlying mechanics are the same. What differs is the expectation: a consumer tolerates instability because the alternative is no access, while a business serving users needs consistency that a tunneled path across an inspected border doesn’t reliably provide.

What should I use instead of a VPN for a China-facing service?

A carrier-optimized route on a named premium path, matched to the carrier your users actually use. CTGNet, CUP, and CMIN2 exist precisely because each of the three Chinese carriers runs a separate network with its own congestion points.

Is it ever appropriate to use a VPN alongside China-optimized hosting?

Yes, for internal use. Connecting your own offices, giving your team administrative access, or keeping a fallback path available are all reasonable. The distinction is that these are your own low-volume operational needs rather than the path your users’ traffic takes.

How can I tell if a VPN is actually hurting my China route’s performance?

Run the same traceroute and sustained ping test with and without the tunnel, at similar times of day, and compare latency, jitter, and loss. If the tunneled path is meaningfully worse across those three, you have your answer without needing to theorize about why.

Quick comparison

1. Riven Cloud

Riven Cloud runs KVM VPS out of Equinix SG1 in Singapore with routing across three named carrier paths, CTGNet (China Telecom, formerly CN2 GIA), CUP (China Unicom), and CMIN2 (China Mobile), rather than a single blended “China-optimized” claim. Our Looking Glass is public, so you can test the exact route before committing to anything, and we’d rather tell you a location or route doesn’t fit your use case up front than have you find out after signing up.

Note: Most of the providers below are competitors to Riven Cloud in the China-optimized Singapore hosting market. We’ve made an intentional effort to represent them fairly. Pricing, specs, and route quality change over time, verify current details directly with each provider before deciding.

2. BandwagonHost

BandwagonHost, operated by IT7 Networks, is a Canadian-headquartered provider with a long-standing presence in the China-optimized VPS space and a Singapore location in Equinix SG1 among its data center options. It’s built a loyal following particularly among smaller-scale users and developers, partly on the strength of budget-friendly plans with CN2 GIA routing available on select locations.

As with any provider in this space, confirm which specific route (CTGNet, still sometimes marketed as CN2 GIA, versus standard transit) applies to the exact Singapore plan you’re looking at, since not every plan tier necessarily includes the premium route.

3. RackNerd

RackNerd has built a reputation in budget VPS hosting more broadly, with a confirmed Singapore data center among its many location options across a wide global footprint. Its pricing is aggressive, often running frequent promotional deals, which makes it a common recommendation for cost-conscious buyers. Network quality and route optimization can vary more by specific promotion and plan tier than with more narrowly focused providers, so it’s worth checking the specific plan’s routing details rather than assuming uniform quality across RackNerd’s entire catalog.

4. GigsGigsCloud

GigsGigsCloud operates a Tier III data center presence in Singapore and has built a specific reputation around China-optimized routing as a core focus rather than a secondary feature, which shows in how deliberately its plans are marketed around specific carrier routes. It tends to skew toward a more technical audience comfortable evaluating routing details directly rather than a general consumer hosting audience.

5. Megalayer

Megalayer maintains a Tier III data center presence in eastern Singapore, with a product lineup that spans VPS, dedicated servers, and colocation, alongside a specific emphasis on China-optimized connectivity. Its broader product range makes it a reasonable option if you expect to need more than a simple VPS down the line, dedicated hardware or colocation, without switching to an entirely different provider for those services.

6. UCloud

UCloud has maintained a Singapore presence since 2016 and operates at a larger scale than most of the other providers on this list, with a broader cloud infrastructure product line beyond simple VPS hosting. It’s a fit for teams that want more cloud-native features (like managed databases or object storage) alongside China-optimized connectivity, rather than a straightforward, no-frills VPS.

7. Zenlayer

Zenlayer operates infrastructure across Asia with a specific focus on connectivity into and out of China, including a Singapore presence as part of its broader regional network. It leans more toward enterprise and larger-scale infrastructure customers than individual developers or small projects, with product offerings that go well beyond a simple VPS, including dedicated connectivity and edge infrastructure services.

8. Alibaba Cloud International

Alibaba Cloud’s international arm operates data centers in Singapore as part of its global infrastructure, and as a subsidiary of a Chinese parent company, it has a structurally different relationship with China-based connectivity than the other providers on this list, worth understanding as a distinct category rather than a direct substitute. It’s a heavier, more enterprise-oriented platform than the more narrowly focused providers above, with a correspondingly steeper learning curve and broader (and more complex) product catalog.

What to verify before choosing any of these

Confirm the specific route on the specific plan. “China-optimized” on a company’s homepage doesn’t guarantee every plan tier includes it. Ask which specific carrier route (CTGNet, CUP, CMIN2, or a generic “CN2 GIA” claim worth double-checking per our earlier guide) applies to the exact plan you’re considering.

Test before committing beyond a trial period. A traceroute or a public looking glass tool tells you far more than a marketing page. If a provider won’t give you a test IP or trial window, that’s worth factoring into the decision itself.

Check current pricing and specs directly. Hosting pricing and available specs shift often, and any comparison written at a point in time can go stale. Confirm current details on each provider’s own site before deciding.

Ask about peak-hour performance, not just off-peak test results, since China-optimized routes can behave differently under real business-hour load than in a quiet 3 a.m. test.

Wrapping up

Singapore’s combination of geographic proximity to China and jurisdiction outside it makes it a genuinely strong location for China-facing infrastructure, and each of the eight providers above has a real, verifiable Singapore presence worth evaluating on its own merits. The right pick depends on your specific carrier-route needs, your comfort with a more technical versus more managed platform, and your own testing, not just whichever name shows up most often in a forum thread.

Want to see how a real China-optimized route performs from Singapore before you commit anywhere? Riven Cloud’s Looking Glass lets you test CTGNet, CUP, and CMIN2 routing from our Singapore location (Equinix SG1) directly. If Riven Cloud ends up being the fit, our Premium plan starts at $49/mo with full root access on either Tokyo or Singapore.

Frequently asked questions about Singapore hosting for China routing

Is Singapore always better than Hong Kong or Tokyo for China-facing hosting?

Not universally. Each location has different strengths depending on carrier routing, jurisdiction preferences, and your specific audience’s location within China. Singapore’s advantage is largely its combination of solid connectivity and being outside Chinese regulatory jurisdiction, not a blanket performance win over every alternative.

Do all these providers offer the same quality of China routing?

No. Even among providers with genuine Singapore data centers, the specific carrier routes offered, and how consistently they perform, vary meaningfully. Always verify the specific route on the specific plan you’re considering.

How do I test China routing quality before committing to a plan?

Ask for a trial period or test IP, and run a traceroute from (or to) a Chinese IP address, or check the provider’s own public looking glass tool if they offer one. Testing at different times of day gives a more complete picture than a single test.

Why isn’t DMIT on this list?

DMIT is a well-known name in the China-optimized VPS space, but as of this writing, its data center locations are Los Angeles, Hong Kong, and Tokyo, not Singapore, which is why it’s not included in a Singapore-specific comparison.

Does a bigger provider always mean better China routing?

Not necessarily. Scale can bring more infrastructure investment, but some smaller, more narrowly focused providers built their entire business around China-optimized routing specifically, which sometimes translates to more attention on that one thing than a larger, broader-focus provider gives it.

Should pricing be the main factor in choosing between these providers?

Pricing matters, but for China-facing infrastructure specifically, route quality and consistency usually matter more, since a cheaper plan with poor peak-hour routing performance can cost more in lost user experience than it saves in monthly fees.

The short version

What each one actually is

CTGNet (formerly CN2 GIA). CTGNet is the more current name China Telecom uses for its premium route, historically marketed as CN2 GIA, and you’ll still see both terms used, sometimes even by the same provider in different places. It’s built to keep traffic on China Telecom’s backbone for a longer stretch of the route than standard transit, avoiding the heaviest congestion points closer to typical international peering locations.

This matters specifically for users on China Telecom’s own network, which is the largest of the three major Chinese carriers and covers a broad geographic footprint across the country.

CUP (China Unicom Premium). CUP is China Unicom’s equivalent premium routing product, built on the same general principle, minimize hops and congestion for traffic destined to Unicom’s network specifically. If your audience or team is concentrated on China Unicom connections rather than China Telecom, a route optimized for CUP will generally outperform a CTGNet route for those specific users, even though CTGNet (still often called CN2 GIA) gets more attention in general hosting discussions.

CMIN2 (China Mobile International N2). CMIN2 is China Mobile’s premium international route, and the newest of the three to become widely available in commercial hosting products. China Mobile has historically been more associated with mobile connectivity than fixed broadband, but its international routing product matters for any service with a meaningful share of China Mobile users, mobile or fixed.

Why three separate routes exist at all

China’s internet infrastructure is split across three major state-affiliated carriers, China Telecom, China Unicom, and China Mobile, each operating largely separate physical networks with their own international gateways and peering arrangements. A route optimized for one carrier’s network doesn’t automatically carry the same benefit for traffic destined to a different carrier’s users, because the physical path and peering points differ.

This is the entire reason multiple “China-optimized” products exist instead of just one: a single premium route can’t be equally optimized for all three carriers simultaneously, since they’re genuinely separate networks with separate congestion points.

Does it matter which one you pick?

It depends entirely on who’s actually accessing your service. If you don’t know your audience’s carrier distribution, the honest answer is that a single “China-optimized” route, whichever one you pick, is a meaningful improvement over standard international transit for a general China-facing audience, but it won’t be equally optimal for every visitor.

If you do know, or can find out, which carrier your specific audience is concentrated on, matching your route to that carrier delivers a bigger improvement than picking whichever route happens to be best-marketed.

Some providers, Riven Cloud included, offer routing across multiple carrier paths specifically because real audiences are rarely on a single carrier exclusively, and covering more than one route reduces the odds that a meaningful chunk of your traffic gets routed sub-optimally.

How to figure out your own audience’s carrier distribution

If you already have traffic data, checking the AS number associated with visiting IP addresses can tell you roughly what share of your China-based visitors are on Telecom, Unicom, or Mobile networks respectively. This isn’t always precise, since some IP ranges are harder to attribute cleanly, but it’s usually enough to identify whether your traffic skews heavily toward one carrier or is genuinely mixed across all three.

A note on naming confusion

Because CTGNet and CN2 GIA refer to the same underlying China Telecom product, and because providers vary in which name they use, don’t assume two providers advertising different names are offering genuinely different routes without checking. Ask directly which carrier and AS numbers are involved, the answer matters more than which of the two interchangeable names shows up on the pricing page.

We list our own routing this way specifically to avoid this kind of ambiguity: Riven Cloud offers CTGNet (China Telecom, AS23764/AS4809), CUP (China Unicom, AS9929/AS10099), and CMIN2 (China Mobile, AS58807) as distinct, named routes rather than a single blended “China-optimized” claim, and our network page lists the exact paths for each.

Wrapping up

There’s no single “best” route among these three, only a best fit for a specific audience’s carrier distribution. If you’re evaluating providers, ask which specific carrier routes they offer, not just whether they have “China optimization” in general, and if you can determine your own audience’s carrier split, use that to guide which route actually matters most for your traffic.

Want to see the exact paths behind each route? Riven Cloud’s Looking Glass lets you test CTGNet, CUP, and CMIN2 independently, from Tokyo or Singapore, before you commit to anything. Once you’ve found the route that fits, Riven Cloud’s Premium plan starts at $49/mo with that same routing built into every plan.

Frequently asked questions about China carrier routing

Are CTGNet and CN2 GIA actually different products?

No, they refer to the same underlying China Telecom premium route. CTGNet is the more current name for what was historically marketed as CN2 GIA, and both terms are still in circulation.

Which route is best if I don’t know my audience’s carrier distribution?

Any of the three premium routes is a meaningful improvement over standard international transit for a general China-facing audience, but for the biggest improvement, look for a provider offering multiple carrier routes rather than betting on just one.

Can I check which carrier my visitors are actually on?

Yes, roughly. Checking the AS number associated with visitor IP addresses can indicate whether traffic is concentrated on Telecom, Unicom, or Mobile, though attribution isn’t always perfectly precise for every IP range.

Is China Mobile’s CMIN2 route as mature as CTGNet?

It’s newer to widespread commercial availability than China Telecom’s product, but it serves the same fundamental purpose for China Mobile’s network specifically, and it’s become a standard offering among providers focused on China-optimized routing.

Do I need all three routes, or is one enough?

It depends on your audience. If your traffic is genuinely concentrated on one carrier, one well-matched route may be sufficient. If your audience is mixed across carriers, coverage across multiple routes reduces the chance that a meaningful share of visitors gets a sub-optimal path.

Does a provider need separate infrastructure for each carrier route?

Generally yes, since each route involves separate peering arrangements and paths to a different carrier’s network. This is part of why not every provider offers all three, and why it’s worth asking specifically which ones a given provider actually supports.

1. Is it CTGNet (CN2 GIA), or just CN2?

These aren’t interchangeable. Regular CN2 is China Telecom’s improved network product, better than standard international transit, but it still typically exits through the same congested peering points as ordinary traffic once it reaches certain points in the path. CTGNet, China Telecom’s current name for what was formerly marketed as CN2 GIA (Global Internet Access), is the premium tier, engineered to stay on China Telecom’s backbone for a longer portion of the route and avoid the worst congestion points entirely.

A provider using “CN2” and “CN2 GIA” interchangeably in its own marketing is a signal to look closer, not a confirmation that you’re getting the premium product.

How to check: ask directly which one you’re getting, and ask for the AS numbers involved in the route. CTGNet routes commonly traverse AS4809 (China Telecom Next Generation Carrier Network, the network CTGNet actually runs on) at some point in the path. A route that never touches AS4809 and only shows the standard CN2 backbone AS number is regular CN2, not the premium tier, no matter what the plan is named.

2. What does a traceroute from a real test IP actually show?

This is the single most useful verification step, and it costs you nothing. A legitimate CN2 GIA route has a specific, recognizable signature: it should stay on China Telecom’s own network for most of the path rather than handing off to a different backbone early, and it should show noticeably fewer hops and lower latency than a standard international route to the same region.

How to check: ask for a test IP before you commit to anything beyond a trial period, and run a traceroute from a Chinese IP or ask the provider to share results from their own looking glass tool. Compare the hop count and latency against what CN2 GIA is known to deliver for that specific route (Shanghai and Beijing routes, for instance, tend to be the best-documented and most consistently good, since they’re the routes providers optimize for and demonstrate first).

3. Does the route cover the specific region you actually care about?

A provider might have genuinely good CTGNet performance to Shanghai and terrible performance to a smaller inland province, because the physical route quality depends on where China Telecom’s backbone actually reaches well versus where it doesn’t. “CN2 GIA available” as a blanket claim doesn’t guarantee uniform performance across every region in China.

How to check: if you know where your specific audience or team is concentrated, ask for a test to that specific location, not just a generic “China” test. A provider confident in their routing will usually accommodate this, and a lot of hesitation around a specific-region test request is itself informative.

4. What happens during peak hours?

CTGNet routes are genuinely good most of the time, but “genuinely good” and “immune to congestion” aren’t the same thing. Some providers oversell capacity on their CTGNet allocation, and a route that performs beautifully at 3 a.m. can degrade noticeably during Chinese business hours when overall demand on that pipe is highest.

How to check: if you’re able to run a trial, test at different times of day, including what would be peak business hours in China, not just whenever happens to be convenient for you. A single good test result from an off-peak hour tells you less than a pattern of results across a full day.

5. Is this route reserved for their own infrastructure, or resold from someone else?

Some providers buy wholesale CN2 GIA capacity from a larger upstream network and resell it, which isn’t inherently a problem, but it does mean the quality and consistency you get depends on a contract you can’t see and a relationship you’re not party to. If the reseller’s upstream provider has a bad month, changes terms, or gets deprioritized, your service quality can shift without warning and without the reseller necessarily being forthcoming about the cause.

How to check: ask directly whether the provider owns the network infrastructure delivering the route or resells it from another network. Neither answer is automatically disqualifying, but a direct answer, and how readily it’s given, tells you something about how transparent the provider is likely to be later if something changes.

6. Does the provider tell you what they don’t offer?

This is less a technical check and more a trust signal, but it’s a meaningful one. A provider willing to say plainly which locations or routes don’t get CTGNet treatment, rather than implying universal coverage through vague marketing language, is more likely to be giving you an accurate picture of the part they are confident about too.

How to check: look for specificity in how the provider describes their own network. Marketing copy that names exact routes, specific AS numbers, and explicit carve-outs for what isn’t covered is a different kind of claim than a page that just says “CN2 GIA available” without further detail.

Putting it together

None of these checks require special tools or technical expertise beyond running a traceroute, which most operating systems support natively, and asking direct questions a legitimate provider should be able to answer without hedging. The pattern to watch for isn’t one bad answer, it’s a provider that’s vague across several of these questions at once, since a network actually built around GIA transit usually has this information readily available and no particular reason to obscure it.

We don’t take a stance on which specific competitors do or don’t meet this bar, that changes over time and is worth checking for yourself, but the six questions above are the right ones to ask regardless of who you’re evaluating.

Ready to see it for yourself? Riven Cloud’s Looking Glass is public, and our network page lists the exact AS numbers and carrier paths behind each of our three China-optimized routes. Run your own traceroute before you commit to anything, from us or from anyone else. When you’re ready to move forward, Riven Cloud’s Premium plan starts at $49/mo with the same routing available on every tier.

Frequently asked questions about verifying CTGNet (CN2 GIA) claims

What’s the fastest way to tell if a provider actually has CTGNet (CN2 GIA)?

A traceroute from (or to) a Chinese IP address is the quickest real check. Look for the route staying on China Telecom’s backbone for most of the path and check whether AS4809 appears in it, rather than handing off to a different network early.

Is regular CN2 bad?

No, it’s a genuine improvement over standard international transit, just not as consistently optimized as CTGNet specifically. The problem isn’t regular CN2 itself, it’s providers marketing it using CTGNet’s reputation (still often called CN2 GIA) without actually delivering the premium tier.

Can CTGNet (CN2 GIA) performance vary by time of day?

Yes. Some providers oversell their CTGNet capacity, which can show up as degraded performance during peak hours even when off-peak tests look great. Testing at multiple times of day gives a more honest picture than a single test.

Does it matter if a provider resells their CTGNet (CN2 GIA) capacity instead of owning it?

Not automatically, but it adds a layer of dependency you can’t directly verify. A reseller’s service quality depends on a contract and relationship you’re not party to, so it’s worth knowing which situation you’re in.

Should I trust a provider’s own looking glass results completely?

Treat them as a useful data point, not the final word. A provider’s own looking glass shows performance from their network’s perspective, which is informative but worth cross-checking with your own independent traceroute if the decision matters enough.

Does good CTGNet (CN2 GIA) performance to Shanghai mean it’ll be good everywhere in China?

Not necessarily. Route quality can vary meaningfully by region within China, so if your audience is concentrated somewhere specific, it’s worth testing that exact region rather than assuming a generic “China” result applies uniformly.

The baseline problem

Standard international transit to and from mainland China tends to route through a limited number of congested peering points, and traffic can bounce through several intermediary networks before reaching its destination. Each additional hop adds latency, and congested peering points during high-traffic periods add unpredictable delay on top of that.

For a server hosted outside China serving users inside China, or vice versa, this baseline path is often the single biggest source of poor performance, more significant than server hardware, more significant than distance in raw kilometers.

The three carriers, and their premium routes

Since China Telecom, China Unicom, and China Mobile operate largely separate networks with their own international gateways, an optimized route built for one carrier doesn’t automatically carry the same benefit to users on a different carrier’s network. Each has built its own premium product to address the same underlying congestion problem.

China Telecom: CTGNet (formerly marketed as CN2 GIA, AS23764 and AS4809) is China Telecom’s premium tier, built on top of CN2 (China Telecom Next Generation Carrier Network), its broader next-generation backbone. Regular CN2 is an improvement over standard transit but still typically exits through some of the same peering points as ordinary traffic at some point in the route. CTGNet is engineered to stay on China Telecom’s backbone for a longer stretch instead, avoiding the worst of that congestion.

China Unicom: CUP (China Unicom Premium, AS9929 and AS10099) is China Unicom’s equivalent product, built on the same general principle of minimizing hops and congestion, but specifically for traffic destined to Unicom’s network. If your audience is concentrated on China Unicom connections rather than China Telecom, a route optimized for CUP will generally outperform a CTGNet route for those specific users.

China Mobile: CMIN2 (China Mobile International N2, AS58807) is China Mobile’s premium international route, and the newest of the three to become widely available in commercial hosting products. China Mobile has historically been more associated with mobile connectivity than fixed broadband, but its international routing product matters for any service with a meaningful share of China Mobile users, mobile or fixed.

Why this matters mechanically, not just as a marketing term

The internet doesn’t route traffic based on geographic distance, it routes based on the specific path of networks and peering agreements between them. Two servers that are physically close together can still have a slow, hop-heavy connection if the networks between them aren’t well peered, while two servers physically farther apart can have a fast, direct connection if they sit on well-connected, directly peered networks.

“China-optimized” routing is specifically about improving that network-level path, not the physical distance, which is why a well-routed server thousands of kilometers away can outperform a poorly routed server that’s physically much closer.

What “optimized” concretely changes

• Fewer hops. A well-optimized route stays on fewer networks for a longer portion of the journey, rather than bouncing across several intermediary networks.
• Avoiding known congestion points. Certain peering points between Chinese carriers and international networks are known bottlenecks during peak hours. Optimized routes are specifically engineered to bypass these where possible.
• More consistent latency, not just lower average latency. A congested standard route might have acceptable average latency but wildly inconsistent performance during peak hours, while a genuinely optimized route tends to hold steadier under load.
• Carrier-specific benefit. Since CTGNet, CUP, and CMIN2 each run on a different carrier’s own network, a route optimized for one doesn’t automatically carry the same benefit for traffic destined to a different carrier’s users.

What it doesn’t fix

Optimized routing improves the network path, but it doesn’t change physical distance entirely, doesn’t guarantee performance to every region within China equally (route quality varies by specific destination, not just by carrier), and doesn’t substitute for adequate server resources on the other end. A well-routed but underpowered server will still perform poorly, the routing and the hardware are separate parts of the overall experience, and it’s worth not conflating “good routing” with “good server.”

How to know if you actually need it

If your service serves a meaningful volume of users or traffic to or from mainland China, and you’ve noticed latency or reliability issues that a standard international server doesn’t explain, China-optimized routing is worth evaluating specifically. If your China-facing traffic is minimal or occasional, the added cost and provider-selection complexity of finding genuinely optimized routing may not be worth it relative to a standard, well-located server elsewhere in Asia.

How to verify a specific provider’s claim

Ask which specific carrier route is involved (CTGNet for China Telecom, CUP for China Unicom, CMIN2 for China Mobile) rather than accepting a generic “China-optimized” claim at face value, since the three carriers require genuinely separate optimized paths.

Run a traceroute from or to a Chinese IP address if you can, and look for the route staying on the relevant carrier’s own backbone for a meaningful portion of the path rather than handing off early to a different network. Testing at different times of day, not just once, gives a more complete picture since some providers oversell their optimized capacity and performance can degrade during peak hours.

Wrapping up

“China-optimized” is a real, meaningful technical claim when it’s backed by an actual premium carrier route like CTGNet, CUP, or CMIN2, and it’s worth understanding the mechanics well enough to tell a genuine claim from a loosely used marketing term. The core idea is simple: keep traffic on a well-connected carrier backbone for as much of the journey as possible, avoiding the congestion points that make standard international transit to and from China unpredictable.

Want to see what an actual optimized route looks like rather than take a marketing claim at face value? Riven Cloud’s Looking Glass is public, showing real routing across CTGNet, CUP, and CMIN2 from our Tokyo and Singapore locations. If you’re ready to put it to the test, Riven Cloud’s Premium plan starts at $49/mo and includes that same routing on every tier.

Frequently asked questions about China-optimized transit

Do China Unicom and China Mobile have their own optimized routes too?

Yes. CTGNet is specific to China Telecom, but China Unicom and China Mobile have their own equivalent premium routes, CUP and CMIN2 respectively, and a route optimized for one carrier doesn’t automatically benefit users on a different carrier’s network.

Does China-optimized routing guarantee good performance everywhere in China?

No. Route quality can vary by specific region within China, since the physical backbone infrastructure doesn’t reach every area equally well. A route can be genuinely excellent to one city and merely average to another.

How is CTGNet different from regular international transit?

Regular international transit routes through whatever standard peering arrangements exist between networks, often hitting congested points along the way. CN2 is China Telecom’s improved backbone, and CTGNet specifically is engineered to avoid the worst of that congestion by staying on the backbone longer.

Can I test a provider’s China-optimized routing before committing?

Yes, and you should. Ask for a trial period or test IP and run a traceroute from or to a Chinese IP address, or check whether the provider offers a public looking glass tool you can test independently.

Does China-optimized routing cost more than standard hosting?

Generally yes, since it requires specific carrier agreements and infrastructure investment that standard international transit doesn’t. Whether the added cost is worth it depends on how much of your actual traffic is China-facing.

Why do some providers still call CTGNet “CN2 GIA”?

Because CTGNet is the more current name China Telecom uses for a product historically marketed as CN2 GIA, and both terms are still in circulation, sometimes even from the same provider in different places. It’s worth asking directly which tier, and which AS numbers, are actually involved.

We picked these apps for technical usefulness rather than GitHub stars, and we have tried to be straightforward about the trade-offs. One habit worth keeping throughout: a public VPS does not mean an app should accept anonymous users. Several entries belong behind authentication, HTTPS, or another access-control layer.

The short list is: Vaultwarden for passwords, Paperless-ngx for documents, FreshRSS for feeds, Forgejo for Git, Umami for analytics, changedetection.io for page monitoring, ntfy for push notifications, SearXNG for private metasearch, Actual for budget synchronization, and linkding for bookmarks.

How these self-hosted apps were selected

We checked every project as of July 19, 2026 against five requirements: active maintenance, an open-source license verified in the canonical repository, an official Docker or self-host installation path, a reason to run continuously on an Internet-connected host, and an operational caveat worth planning around. “Best” here means the app clears those filters and earns its keep on an always-on server, with trade-offs we can explain honestly. The ten apps are listed in no particular order.

Awesome-Selfhosted was the discovery baseline. As of July 19, 2026, it contained 1,249 software entries across 94 categories, including 698 Docker-tagged entries; its GitHub repository had about 306,462 stars when checked. Use the recommended HTML catalog for browsing. The GitHub Markdown list is generated and retained as a legacy interface.

Those numbers describe the catalog as a whole; a listing is a discovery signal, not a security audit or a deployment endorsement. License labels can also lag canonical sources. As of the same July 19, 2026 check, Vaultwarden is listed there as GPL-3.0 although its repository declares AGPL-3.0, while Forgejo is listed as MIT although its canonical Codeberg repository uses GPL-3.0-or-later. Those mislabels are why we verified each license at the source.

Quick comparison

The table describes workload shape rather than invented RAM minimums. A mostly idle service can become busy with many users, aggressive polling, large imports, or long retention.

1. Vaultwarden: password synchronization

Vaultwarden gives individuals, families, and small teams a lightweight sync server for the Bitwarden clients they already use. It is an unofficial implementation of the Bitwarden client API, not a Bitwarden, Inc. product. Choose the official Bitwarden server when exact upstream behavior, formal support, or organizational compliance takes priority.

The current license is AGPL-3.0. Its official installation path supports a single application container through Docker, Podman, or Compose, normally behind an HTTPS reverse proxy. Mobile, desktop, browser, and CLI clients can all reach one stable VPS endpoint without opening a home network.

Treat the server as a high-value target. Disable open registration when it is unnecessary, protect the admin interface and token, enable MFA where appropriate, and keep the image current. Backups need the database, attachments, and configuration rather than a copy of the disposable container. The Vaultwarden Docker tutorial walks through registration lockdown, client synchronization, SQLite-safe backup, and an isolated restore test.

2. Paperless-ngx: searchable document storage

Paperless-ngx watches an inbox, runs OCR, applies metadata, and makes scanned paperwork searchable from different devices. That processing can continue on an always-on VPS while your laptop is offline.

The project uses GPL-3.0. Its official setup guide recommends Docker Compose, with the web application, a Redis-compatible broker, and a database as distinct responsibilities. Current guidance recommends PostgreSQL for new installations. Tika and Gotenberg are optional additions for relevant Office document formats.

OCR and conversion create short CPU and memory bursts, while originals and indexes create lasting storage pressure. The harder issue is trust: Paperless-ngx states that documents are stored in clear text and should not run on an untrusted host. Use authenticated HTTPS, harden the host, restrict administrative access, and encrypt backup destinations. Decide whether the VPS operator, host configuration, and recovery copies are suitable before uploading identity, tax, medical, or legal records. A local server is the safer fit when that trust requirement cannot be met. The Paperless-ngx Docker Compose guide works through PostgreSQL setup, a real OCR acceptance test, and an empty same-version restore.

3. FreshRSS: an always-on feed reader

FreshRSS keeps polling feeds after your personal devices go to sleep. It also synchronizes subscriptions, read state, and favorites across browsers and compatible mobile clients. Publishers that support WebSub can deliver updates directly.

FreshRSS is AGPL-3.0, and the project maintains an official Docker deployment. It is a PHP application with a choice of SQLite, PostgreSQL, MariaDB, or MySQL. Small private installs can keep the shape simple; larger ones can move the database out of the app container.

Feed count, refresh frequency, full-text scraping, and retention drive load. Schedule refresh jobs deliberately, watch slow or failed sources, and avoid hammering publishers. Database and configuration backups matter more than container backups. Use the FreshRSS Docker guide to configure the private first-run path and refresh scheduler.

4. Forgejo: Git hosting for a small team

Webhooks need a reachable endpoint, and Git over SSH or HTTPS benefits from a stable hostname. Forgejo supplies both, alongside repositories, issues, pull requests, packages, and releases for a developer or small team.

The canonical license is GPL-3.0-or-later. Forgejo provides an official container installation and can start with SQLite or use an external database. The server may be modest when traffic is low, but repository history, Git LFS objects, packages, release files, and Actions artifacts can fill NVMe storage much sooner than the web interface suggests.

Forgejo Actions runners are separate from the server. They execute workflow code and need their own isolation, patching, capacity, and trust policy. Do not size the forge as if runners were free background threads. Disable public registration unless you are prepared to handle spam and abuse. The Forgejo Docker guide keeps server deployment separate from runner trust decisions.

5. Umami: web analytics on your own collector

Every site measured by Umami sends events to its collection endpoint. Hosting that endpoint on an always-on VPS gives several sites one reachable collector and one operator-controlled dashboard.

Umami has an MIT license. Its installation guide covers Docker Compose and prebuilt images, but this is not a single-container database-free service. PostgreSQL is required, and current documentation specifies PostgreSQL 12.14 or newer and recommends UTC.

Event volume, data retention, bot traffic, and report queries determine database growth and load. Set retention with storage in mind, back up PostgreSQL consistently, and monitor ingestion rather than judging capacity from dashboard activity. Self-hosting controls where the collector runs; it does not remove privacy, consent, or data-retention obligations. The Umami Docker deployment pairs PostgreSQL backup and restore with a tested reverse-proxy path.

6. changedetection.io: scheduled page monitoring

Price, stock, policy, and content pages rarely change on your schedule. changedetection.io checks them on its own schedule and can send results to browser extensions, notification services, or API integrations. A VPS supplies the continuous scheduler and outbound Internet access.

The project is Apache-2.0, with official Docker and Compose instructions. Basic HTML fetches are relatively simple. JavaScript-heavy targets may need WebDriver, Playwright, or the recommended browser service, which adds Chromium processes and much more variable CPU and memory use.

Network behavior is often the limiting factor. Target sites may rate-limit or block a data center IP, and more compute will not fix that. Set sensible intervals, respect target policies, and do not turn the service into an aggressive scraper. If optional AI summaries are enabled, monitored content is sent to the configured external AI provider, so review that data flow before using it on private pages. Start with the plain HTTP fetcher in the changedetection.io Docker Compose guide and add browser automation only when a target requires it.

7. ntfy: HTTP push notifications

A backup job can send one HTTP request to ntfy, and a subscribed phone or browser can receive the result. The same small interface works for cron, CI, monitoring, and home automation. Hosting it on a VPS makes it reachable across otherwise separate networks.

ntfy is dual-licensed under Apache-2.0 and GPL-2.0. The official self-hosting guide supports a compact Go server, with SQLite used by default for persistence.

The easy publish model can also be dangerously open. A guessable topic name is not access control. Configure authentication, deny-by-default permissions where appropriate, HTTPS, rate limits, and persistent volumes. Retained messages and attachments consume disk and monthly transfer. Default SQLite storage is single-writer, so it should not be presented as a horizontally scalable cluster. The ntfy Docker guide starts from a closed access policy.

8. SearXNG: private metasearch with external dependencies

SearXNG aggregates results from multiple search sources; it does not build an independent web index. A private VPS instance keeps the interface and its preferences available across your devices.

SearXNG uses AGPL-3.0, and the project publishes an official container installation. Run it as an authenticated private service. An unrestricted domain invites bot traffic, raises the chance that upstream engines classify the VPS address as abusive, and may violate a provider’s acceptable-use rules.

Queries still go to upstream engines. Those services can return CAPTCHAs, throttle requests, or block data center IPs, so self-hosting does not remove the external dependency. The official limiter uses Valkey and helps control inbound bots, but it cannot guarantee acceptance by an upstream provider or replace access control. The private SearXNG Docker Compose deployment puts Caddy authentication in front of Valkey-backed limiting and exact trusted-proxy handling.

9. Actual: private budget synchronization

Actual is local-first, but its server lets devices and users synchronize a budget without leaving one laptop online. End-to-end encryption is optional, requires a second password, and must be enabled separately for each budget. The VPS is a private sync endpoint, not a public finance portal or a business accounting system.

Actual has an MIT license and an official Docker installation path. Put the server behind a correctly configured reverse proxy with HTTPS, enable authentication and end-to-end encryption for each budget, keep it updated, and test backups. Exposing its raw application port is not a finished deployment.

Financial records increase the cost of a weak setup. Protect credentials, restrict access where practical, and verify that a restored server can reopen and synchronize the budget. Bank-sync tokens are stored separately from budget data and are not covered by Actual’s end-to-end encryption; a server administrator or hosting provider with database access can read them. If your only device already provides enough local-first functionality, the extra Internet-facing service may not be worth maintaining. In the Actual Budget Docker Compose guide, server login, optional budget E2EE, two-client sync, and full-state recovery remain distinct tests.

10. linkding: centralized bookmarks

Bookmarks become more useful when the same searchable collection follows you between browsers and devices. linkding provides that endpoint for extensions, a bookmarklet, REST clients, and mobile apps. It is small enough to operate without turning bookmark capture into an infrastructure project.

The project is MIT-licensed. Its installation guide covers Docker, Compose, user creation, persistent storage, and reverse-proxy setup. SQLite is the default and PostgreSQL is available.

The basic deployment is straightforward, but the latest-plus image adds Chromium-based page archiving. That image is larger, browser processes use more memory, and saved snapshots make disk consumption grow with the collection. Back up the persistent database and archived assets rather than the replaceable container. If full archival is the primary job, a dedicated archive system may be a better fit than turning every bookmark into a snapshot. The linkding Docker Compose guide combines a private administrator bootstrap with application backups, isolated recovery, and tested egress blocks.

Why some popular self-hosted apps are absent

Home Assistant is usually most useful near local radios, sensors, and household devices. A VPS can host parts of the stack, but moving the primary controller away from the LAN adds dependence on the Internet path and complicates local hardware access.

Pi-hole and AdGuard Home are DNS resolvers first. Running one on a VPS can work only for clients reached through a deliberately restricted private-access design, but exposing an open recursive resolver is an abuse and amplification risk. A VPS-first recommendation needs complete access controls and resolver safeguards, not a public port 53 recipe.

Jellyfin and Immich are dominated by media storage, upload and download transfer, thumbnail or transcoding work, and sometimes GPU requirements. A storage-oriented home server or dedicated media host is often a better match than a general-purpose VPS with a monthly transfer quota.

Nextcloud can run well on a VPS, but it brings a larger operations footprint: database tuning, caching, background jobs, upgrades, file locking, storage growth, and recovery planning. It deserves a dedicated architecture guide rather than a casual place in a compact VPS-first list.

Shared deployment rules

Put each public web interface behind a maintained reverse proxy with valid TLS. Bind internal application and database ports to localhost or a private container network. Disable open registration unless it is intentional, use unique credentials, and enable MFA where the app supports it.

Container updates still require judgment. Pin stable versions or review release notes before automated updates, and keep a rollback path. Back up application data, databases, uploads, encryption material, and configuration. A running container does not prove that its data can be restored.

Watch disk growth in the places each app creates durable data: document originals, Git objects, analytics events, notification attachments, and page archives. Observe real CPU and memory use during OCR or browser automation before setting tight container limits. Apps that fetch arbitrary URLs also need outbound controls and protection against requests to internal metadata or private services.

Choosing VPS resources and location

Application count is a poor sizing metric. Workload shape, concurrency, retained data, and failure tolerance matter more. A few mostly idle private services behave differently from PostgreSQL analytics ingestion, document OCR, Chromium fetchers, or an Actions runner, even if both deployments contain the same number of containers.

For a few of the lighter services here, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable starting point. Add heavier jobs such as OCR, Chromium fetchers, or analytics ingestion and Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) buys useful headroom, while Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB) suits a fuller stack. Measure the heaviest jobs, watch how durable data grows, and keep an eye on monthly transfer if you host analytics collection, attachments, package hosting, or large Git operations.

Every plan includes daily backups, a 1 Gbps port, and full root access. Our VPS plans are unmanaged, so you run Linux, Docker, TLS, and the applications yourself and keep full control. Treat the daily backups as a safety net: pair them with application-consistent database dumps, off-server copies, and the occasional restore test.

Choose Tokyo or Singapore based on the people, websites, and upstream APIs that will use the service. If your users are in mainland China, it is worth a few minutes on the Tokyo Looking Glass and Singapore Looking Glass from their access networks. We carry the three major mainland carriers over CTGNet (formerly China Telecom CN2 GIA, AS23764 / AS4809), China Unicom Premium (CUP, AS9929 / AS10099), and China Mobile International N2 (CMIN2, AS58807), and the best judge of any route is a test of the actual path at the hours that matter to you.

When you have a feel for the workload, compare it against Riven Cloud pricing. Start with the service whose failure you can recover from, confirm its backup restore, then add the next one. An app earns its place when its always-on benefit is worth its biggest caveat.

This guide deploys Actual Budget 26.7.0, the current release when we checked on July 18, 2026, from the official Docker Hub image on a Debian or Ubuntu VPS. Docker publishes port 5006 only on loopback. You set the server password through an SSH tunnel before Caddy exposes budget.example.com, then test a real budget from two clients.

Prerequisites

You need:

• a Debian or Ubuntu VPS with root or sudo access;
• an A record for budget.example.com pointing to the VPS, plus an AAAA record only when IPv6 is configured and filtered correctly;
• TCP 80 and 443 open for Caddy, along with your administrative SSH port;
• a modern browser on two devices, or two isolated browser profiles;
• encrypted storage outside the VPS for budget exports and server backups.

First install Docker Engine and the Compose plugin. Docker’s convenience script is the fastest route; if running a downloaded script as root is against your policy, your distribution’s packages work too. Then add Caddy and UFW:

curl -fsSL https://get.docker.com | sudo bash
sudo docker compose version

sudo apt update
sudo apt install -y caddy ufw

Allow SSH before enabling the firewall. Replace port 22 if the host uses another administrative SSH port; our guide to securing SSH on a VPS covers moving the port and hardening logins without locking yourself out:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Mirror those inbound rules in any provider firewall. Do not open port 5006 publicly.

Create the Actual Budget Compose project

The official Docker configuration runs one actual-server service, mounts /data, and uses node scripts/health-check.js as its health check. The file below keeps that health check and adds a pinned version, a loopback-only host port, and log rotation.

As of the 26.7.0 image (checked July 18, 2026), the image creates an actual account with UID/GID 1001, but its OCI configuration does not select that account, so the container runs as root by default; a later image may change this, so recheck after upgrades. Create a root-owned data directory to match. Do not add user: "1001:1001" until you have proved that startup, writes, upgrades, backup, and restore all work under that override.

sudo install -d -m 750 /opt/actual
sudo install -d -m 750 /opt/actual/actual-data
cd /opt/actual

Create /opt/actual/compose.yaml:

sudo tee compose.yaml > /dev/null <<'YAML'
services:
  actual_server:
    image: docker.io/actualbudget/actual-server:26.7.0
    container_name: actual-server
    restart: unless-stopped
    ports:
      - "127.0.0.1:5006:5006"
    volumes:
      - ./actual-data:/data
    healthcheck:
      test: ["CMD-SHELL", "node scripts/health-check.js"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 20s
    logging:
      options:
        max-size: "10m"
        max-file: "3"
YAML

/data/server-files/account.sqlite stores the hashed server password, sessions, and the server’s budget-file registry. Budget blobs live under /data/user-files. The server configuration reference documents those paths and the supported environment variables. Keeping the defaults puts the whole server state under one mount.

Start it and check the listener:

cd /opt/actual
sudo docker compose up -d --wait --wait-timeout 120
curl -fsS http://127.0.0.1:5006/health
sudo ss -lntp | grep ':5006'

The health endpoint should return {"status":"UP"}, and the listener must show 127.0.0.1:5006, not 0.0.0.0:5006 or [::]:5006.

Initialize the password through an SSH tunnel

An uninitialized Actual server asks the first visitor to set its server password. Do that privately before adding a public Caddy route.

From your workstation, open a tunnel and leave it running:

ssh -N -L 5006:127.0.0.1:5006 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:5006. Set a long, unique server password and store it in a password manager. This is the login password for the server, not an end-to-end encryption password.

Sign out, reload the page, and sign in again. Also try a wrong password. If the original setup screen reappears or the wrong password works, check the actual-data ownership and container logs before continuing.

The official password reset procedure runs a script inside the container, which means anyone with root or Docker access can reset the server authentication boundary. Limit administrative access to the VPS accordingly.

Add Caddy without replacing Actual’s security headers

Actual needs HTTPS and cross-origin isolation for the SharedArrayBuffer used by its browser-side SQLite engine. The server sets these response headers itself:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

The official reverse-proxy guide warns that duplicate COOP or COEP headers can cause a fatal SharedArrayBufferMissing error. Caddy passes the upstream headers through, so use a plain reverse proxy and do not add another copy.

Create the site after the private password test has passed. Keep site snippets in a separate imported file so adding Actual does not erase other Caddy hosts; the conditional import appends the top-level import only when the main file lacks it:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/actual.caddy > /dev/null <<'CADDY'
budget.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:5006
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy obtains and renews the certificate once DNS and both firewalls allow TCP 80/443. Check the public path and the headers:

curl -fsS https://budget.example.com/health
curl -fsSI https://budget.example.com/ | grep -i '^cross-origin'

The header check should print exactly one Cross-Origin-Opener-Policy: same-origin and one Cross-Origin-Embedder-Policy: require-corp. Open the browser console and confirm there is no SharedArrayBufferMissing error.

Prove budget creation and two-client sync

A healthy endpoint proves that Node can answer a request. It does not prove that a budget can be written, downloaded, decrypted, or synchronized.

In the first browser:

1. Sign in at https://budget.example.com.
2. Create a budget named VPS restore test.
3. Add an account named Checking test with an opening balance of 1,000.
4. Add a transaction for 12.34 with payee Compose test and a note containing today’s date.
5. Wait for the sync indicator to settle, then reload and confirm the balance and transaction remain.

Open a private window, a separate browser profile, or a second device with no Actual local storage. Sign in to the same server, select the cloud budget, and let it download. Confirm the account, exact transaction amount, payee, note, and resulting balance.

Make a second change from that client, such as changing the note to Second client sync works. Wait for sync, return to the first client, and confirm the edit arrives. Avoid simultaneous edits to the same field during this acceptance test. Actual supports concurrent clients, but a deterministic test is easier to diagnose.

Decide whether to enable budget encryption

Actual’s sync documentation describes optional end-to-end encryption per budget. Enabling it creates a second password that should differ from the server login password. The client encrypts budget data before upload, and each new device needs that second password once to derive the key.

Four boundaries matter:

• Encryption is optional and applies per budget, not automatically to every file on the server.
• It cannot be switched off in place. Returning to an unencrypted file requires an export and import.
• If every local copy is gone and the encryption password is forgotten, the budget cannot be recovered. A device that still has a local copy may reset sync and create a new key.
• Local browser or desktop data remains unencrypted. Use full-disk encryption on every client device.

If you enable encryption, open the budget settings, choose Enable encryption, save the second password separately, and repeat the clean second-client download. The second client must ask for the encryption password and then show the same transaction.

Bank sync has a different trust boundary. Actual’s bank-sync documentation states that API keys, secrets, and bank-sync tokens are stored on the server, outside budget E2EE. A server administrator, hosting provider, or attacker with direct database access can read them. Keep those credentials out of Compose files, shell history, screenshots, and tickets, and encrypt backups that may contain them. Actual also requires the user to trigger bank sync; this guide does not assume an unattended schedule.

Export each budget and back up all of /data

Actual provides a portable application backup. Open each budget, go to its settings, choose Export Data, and save the Actual ZIP. The official backup and restore guides use that ZIP for import into a new budget. Export every budget separately and keep the old budget until the imported copy has been checked.

The ZIP is not the complete server. A stopped archive of /data also covers authentication, sessions, the server’s file registry, all budget blobs, and server-side bank-sync state. Take both.

Create a consistent archive with Actual stopped:

cd /opt/actual
sudo install -d -m 700 /var/backups/actual
archive="/var/backups/actual/actual-$(date +%F-%H%M%S).tar.gz"

sudo docker compose stop actual_server
sudo tar --numeric-owner --xattrs --acls -C /opt/actual \
  -czf "$archive" actual-data compose.yaml
sudo docker compose start actual_server

sudo chmod 600 "$archive"
sudo sha256sum "$archive" | sudo tee "$archive.sha256" > /dev/null
sudo chmod 600 "$archive.sha256"
curl -fsS --retry 12 --retry-delay 5 --retry-all-errors \
  http://127.0.0.1:5006/health

Encrypt the archive and the ZIP exports, then copy them off the VPS. A backup that exists only on the same disk is not a disaster-recovery copy.

Restore the same version in isolation

Test the archive without touching production. The drill below verifies the checksum, extracts into a fresh directory, and runs a separate Compose project on loopback port 15006 with an internal Docker network that has no external route. That last control keeps the restored server from contacting real bank-sync providers.

BACKUP=$(ls -1 /var/backups/actual/actual-*.tar.gz | sort | tail -n 1)
sudo sha256sum -c "$BACKUP.sha256"

restore_dir="/opt/actual-restore-$(date +%Y%m%d%H%M%S)"
sudo install -d -m 700 "$restore_dir"
sudo tar --numeric-owner --xattrs --acls -C "$restore_dir" -xzf "$BACKUP"
cd "$restore_dir"

Create compose.restore.yaml in that directory:

services:
  actual_server:
    image: docker.io/actualbudget/actual-server:26.7.0
    ports:
      - "127.0.0.1:15006:5006"
    volumes:
      - ./actual-data:/data
    healthcheck:
      test: ["CMD-SHELL", "node scripts/health-check.js"]
      interval: 20s
      timeout: 10s
      retries: 6
      start_period: 20s
    networks:
      - restore_only
    restart: "no"

networks:
  restore_only:
    internal: true

Start only the isolated copy:

sudo docker compose -p actual-restore \
  -f compose.restore.yaml up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:15006/health

Tunnel workstation port 15006 to the restored listener, sign in, open VPS restore test, and verify the known balance and transaction. If E2EE is enabled, supply its separate password. Do not click Bank Sync; the internal network should make any accidental provider connection fail, but restraint is still part of the test.

Also import one application ZIP as a new budget and compare accounts, balances, categories, and transactions. That proves both recovery paths. Tear down the isolated project after recording the result:

sudo docker compose -p actual-restore -f compose.restore.yaml down

Upgrade with a data-aware rollback

Read the Actual release notes before changing versions. Export every budget, take a stopped full backup, and complete the isolated restore first. Then replace the version tag in compose.yaml with the reviewed target:

cd /opt/actual
sudo docker compose pull actual_server
sudo docker compose up -d --wait --wait-timeout 180
curl -fsS https://budget.example.com/health
curl -fsS https://budget.example.com/info

The info endpoint should report the new version. Repeat login, budget opening, a new transaction, and second-client sync, and check the COOP and COEP headers again. Actual may migrate budget or server data during an upgrade, so switching the image back is not a complete rollback. If the upgrade fails, stop the new container, keep the upgraded /data for diagnosis, and restore the old 26.7.0 image definition together with the pre-upgrade /data archive. Start that matched pair and rerun the acceptance test.

Choosing a Riven Cloud VPS for Actual Budget

Actual Budget is a light workload. For a household or small-team budget server, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is plenty, with room left over for a couple of other small containers. Step up to Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB transfer) or Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) if you plan to co-host heavier services (our best self-hosted apps guide has candidates worth pairing with a budget server) or want more space for years of budgets and backup archives on the same disk.

Every plan has a 1 Gbps port, full root access, and a choice of Tokyo or Singapore, so pick the location closest to the people who open and sync budgets. If you connect from mainland China, it is worth a minute to run the Tokyo Looking Glass and Singapore Looking Glass from your own carrier before deciding. The Riven Cloud VPS pricing page has the current plan details.

Our plans are unmanaged, so you run the stack yourself and keep full control, and every plan includes daily backups on our side. Those cover whole-host recovery nicely; keep the per-budget ZIP exports, the stopped /data archive, and the restore drill above in your routine as well, since application-level recovery is the part only you can test.

Security limits and non-fit cases

Keep port 5006 on loopback, patch the host and container, restrict Docker access, and monitor failed logins and disk usage. Use unique server and E2EE passwords. Treat bank tokens and every full backup as financial secrets. Do not co-host Actual with untrusted containers that get the Docker socket or broad access to /opt/actual.

Self-hosting Actual works best when someone clearly owns TLS, updates, monitoring, encrypted off-server backups, and restore tests. If your situation calls for managed key custody, audited access controls, high availability, or a contractual SLA, a hosted service with the right bank-integration model will serve you better; optional budget E2EE does not make bank credentials unreadable to the server operator, so it cannot stand in for that kind of control.

The stack follows the official core plus Valkey architecture and pins the official SearXNG image tag 2026.7.13-9e25585ae. Caddy adds TLS and bcrypt-backed Basic authentication. Only Caddy publishes host ports; SearXNG port 8080 and Valkey port 6379 stay inside a fixed Docker subnet.

The limiter needs accurate client addresses and Valkey state, but it only shapes request behavior after authentication; deciding who may use the service stays Caddy’s job.

Prepare the VPS and DNS

You need a Debian or Ubuntu VPS with root or sudo access, an A record for search.example.com, and an AAAA record only when IPv6 works end to end. TCP 80 and 443 must reach the VPS for Caddy. Keep the administrative SSH port open, and leave 8080 and 6379 closed in UFW, security groups, and the provider firewall; only Caddy needs to be reachable from outside.

Install Docker Engine and the Compose plugin with Docker’s convenience script (inspect it first if that worries you; on a tightly managed host, use your distribution’s packages instead), then confirm the domain resolves:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo bash get-docker.sh
sudo docker compose version
getent ahosts search.example.com

The sudo docker compose version check above is the only privileged docker call in this guide; the later docker commands run unprivileged, so add your user to the docker group (sudo usermod -aG docker $USER, then log out and back in) or run them with sudo yourself.

If UFW is active, retain its working SSH rule and add only the public web ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

The old searxng/searxng-docker repository is archived, so skip it for a new deployment. As of July 18, 2026, the maintained container template lives in the SearXNG core repository and defines core plus valkey.

Generate the configuration and secret

Create a private project directory, an application secret, and a Caddy password hash. SearXNG’s entrypoint generates a random secret when it creates a missing settings.yml; because this setup supplies its own settings file, it sets SEARXNG_SECRET explicitly. The Caddy password lives only in a transient shell variable, and .env stores the bcrypt hash rather than the plaintext.

sudo install -d -m 750 -o "$USER" -g "$USER" /opt/searxng
cd /opt/searxng
umask 077
install -d -m 700 core-config
read -rp 'Private SearXNG username: ' SEARCH_USER
case "$SEARCH_USER" in
  ''|*[!A-Za-z0-9._-]*)
    echo 'Use only letters, digits, dot, underscore, or hyphen' >&2
    exit 1
    ;;
esac
read -rsp 'Private SearXNG password: ' SEARCH_PASSWORD
printf '\n'
SEARCH_PASSWORD_HASH=$(docker run --rm \
  caddy:2-alpine \
  caddy hash-password --algorithm bcrypt --plaintext "$SEARCH_PASSWORD")
unset SEARCH_PASSWORD
{
  printf 'SEARXNG_SECRET=%s\n' "$(openssl rand -hex 32)"
  printf 'SEARCH_USER=%s\n' "$SEARCH_USER"
  printf "SEARCH_PASSWORD_HASH='%s'\n" "$SEARCH_PASSWORD_HASH"
  printf '%s\n' \
    'SEARXNG_BASE_URL=https://search.example.com/' \
    'SEARXNG_BIND_ADDRESS=0.0.0.0' \
    'SEARXNG_PORT=8080' \
    'SEARXNG_LIMITER=true' \
    'SEARXNG_PUBLIC_INSTANCE=false' \
    'SEARXNG_IMAGE_PROXY=true' \
    'SEARXNG_VALKEY_URL=valkey://valkey:6379/0'
} > .env
chmod 600 .env
unset SEARCH_USER SEARCH_PASSWORD_HASH

Keep the secret and bcrypt hash unchanged across ordinary restarts and restores, and keep .env out of tickets, shell transcripts, and repositories. SearXNG’s server settings reference documents the server overrides. SEARXNG_PUBLIC_INSTANCE=false matches this authenticated deployment; access control comes from Caddy, not that flag.

Create /opt/searxng/core-config/settings.yml:

use_default_settings: true

Create /opt/searxng/core-config/limiter.toml:

[botdetection]
ipv4_prefix = 32
ipv6_prefix = 48
trusted_proxies = [
  "172.30.0.2/32"
]

[botdetection.ip_limit]
filter_link_local = false
link_token = true

[botdetection.ip_lists]
block_ip = []
pass_ip = []
pass_searxng_org = true

The limiter documentation explains how SearXNG walks forwarded addresses past trusted proxies. The /32 trusts only Caddy’s fixed address inside the private 172.30.0.0/24 proxy subnet. Trusting every RFC1918 range would allow another container or an accidentally exposed proxy to supply a forged client address. Add a pass_ip only for a monitored source you control; passed addresses also skip other bot checks.

Create the core, Valkey, and Caddy services

Create /opt/searxng/Caddyfile:

search.example.com {
    encode zstd gzip
    basic_auth {
        {$SEARCH_USER} {$SEARCH_PASSWORD_HASH}
    }
    reverse_proxy core:8080
}

Caddy is not part of the official SearXNG Compose template; this integration relies on its documented automatic HTTPS and reverse proxy behavior. Caddy sets the forwarded host, scheme, and client chain and ignores spoofed incoming forwarded values by default.

Create /opt/searxng/compose.yml:

services:
  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    environment:
      SEARCH_USER: ${SEARCH_USER}
      SEARCH_PASSWORD_HASH: ${SEARCH_PASSWORD_HASH}
    networks:
      proxy:
        ipv4_address: 172.30.0.2

  core:
    image: searxng/searxng:2026.7.13-9e25585ae
    env_file:
      - ./.env
    volumes:
      - ./core-config:/etc/searxng
      - core-data:/var/cache/searxng
    networks:
      proxy:
        ipv4_address: 172.30.0.3
    depends_on:
      valkey:
        condition: service_healthy
    restart: unless-stopped

  valkey:
    image: valkey/valkey:9-alpine
    command: valkey-server --save 30 1 --loglevel warning
    volumes:
      - valkey-data:/data
    networks:
      proxy:
        ipv4_address: 172.30.0.4
    healthcheck:
      test: ["CMD", "valkey-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 6
    restart: unless-stopped

networks:
  proxy:
    ipam:
      config:
        - subnet: 172.30.0.0/24

volumes:
  core-data:
  valkey-data:
  caddy-data:
  caddy-config:

The SearXNG service has no ports entry. Valkey has neither ports nor a password because only containers on this project network can reach it; publishing 6379 would break that boundary. The core service loads the whole mode-600 .env file through env_file, which is where it gets SEARXNG_SECRET. Caddy deliberately does not: its environment block passes only the username and bcrypt hash, which Compose interpolates from the same .env in the project directory, so the application secret never enters the Caddy container. Basic credentials are safe in transit only over TLS, so do not publish an HTTP-only route.

Start the deployment and inspect all three services:

cd /opt/searxng
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100 core valkey caddy

Test Valkey, TLS, search, and the limiter

Read the credentials, then check the state service and the authenticated HTTPS path:

cd /opt/searxng
SEARCH_USER=$(sed -n 's/^SEARCH_USER=//p' .env)
read -rsp 'Private SearXNG password: ' SEARCH_PASSWORD
printf '\n'
docker compose exec valkey valkey-cli ping
curl -fsSI -u "$SEARCH_USER:$SEARCH_PASSWORD" https://search.example.com/

Valkey must return PONG and the authenticated request must succeed. Next, prove that an unauthenticated request is refused and that Docker has not opened the private ports on the host:

curl -sS -o /dev/null -w '%{http_code}\n' https://search.example.com/
sudo ss -lntp | grep -E ':(8080|6379)\b'

The first command must print 401; the second must print nothing.

The default output format is HTML, so test with a real search rather than a JSON endpoint. Send browser-like headers and require at least one rendered result:

curl -fsS \
  -u "$SEARCH_USER:$SEARCH_PASSWORD" \
  -A 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/126 Safari/537.36' \
  -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
  -H 'Accept-Language: en-US,en;q=0.8' \
  -H 'Accept-Encoding: gzip, deflate, br' \
  --compressed \
  --data-urlencode 'q=SearXNG metasearch' \
  https://search.example.com/search \
  -o /tmp/searxng-search.html
grep -q '<article class="result ' /tmp/searxng-search.html
rm /tmp/searxng-search.html

Repeat the search in a real browser and open one result. If the page fills with engine errors, the search did not really succeed; the error messages and logs will tell you why.

Now send an intentionally bot-like burst. The limiter checks more than request counts, including request headers and user-agent behavior, so exact rejection timing depends on the current limiter.toml:

for request in $(seq 1 20); do
  curl -sS -o /dev/null -w '%{http_code}\n' \
    -u "$SEARCH_USER:$SEARCH_PASSWORD" \
    -A 'curl/limiter-test' \
    'https://search.example.com/search?q=limiter-test'
done | sort | uniq -c

docker compose logs --since=10m core valkey caddy | \
  grep -Ei 'limiter|bot|429|403|valkey|error' || true
unset SEARCH_PASSWORD

The burst should produce blocked responses, commonly 403 or 429, while the browser-like search stays usable. If every request appears to come from 172.30.0.2, stop and fix trusted_proxies; raising limits would only hide the proxy error. Check the logs for Valkey connection failures. The limiter is not access control: it can throttle an accepted request, but only Caddy’s authentication decides whether a request reaches SearXNG.

Understand the privacy boundary

SearXNG’s own-instance documentation explains that it does not forward a user’s cookies to search engines and presents generated request profiles. The selected upstream engines still receive the search terms because they need the query to return results. They normally see the VPS exit IP instead of the user’s IP.

A private instance used by one person can still be linkable through its stable exit address, timing, and query content. Multiple authenticated users send more queries from one data-center IP and may trigger upstream rate limits, CAPTCHA challenges, or an IP block; SearXNG cannot promise that every engine stays available. And to repeat the house rule from the top: please keep Tor, relay, and open-proxy functionality off this deployment, as our AUP does not allow them.

Back up configuration and both data volumes

SearXNG has no application-level backup tool. This procedure follows its documented persistent paths and Docker’s volume backup guidance. It stops the whole project so the core cache and the Valkey snapshot belong to one recovery point:

cd /opt/searxng
umask 077
install -d -m 700 backups
core_volume=$(docker inspect -f \
  '{{range .Mounts}}{{if eq .Destination "/var/cache/searxng"}}{{.Name}}{{end}}{{end}}' \
  "$(docker compose ps -q core)")
valkey_volume=$(docker inspect -f \
  '{{range .Mounts}}{{if eq .Destination "/data"}}{{.Name}}{{end}}{{end}}' \
  "$(docker compose ps -q valkey)")
stamp=$(date +%F-%H%M%S)

docker compose stop
sudo tar -czf "backups/searxng-config-$stamp.tar.gz" \
  compose.yml Caddyfile .env core-config
docker run --rm -v "$core_volume:/source:ro" -v "$PWD/backups:/backup" \
  alpine:3.22 \
  tar -C /source -czf "/backup/searxng-core-$stamp.tar.gz" .
docker run --rm -v "$valkey_volume:/source:ro" -v "$PWD/backups:/backup" \
  alpine:3.22 \
  tar -C /source -czf "/backup/searxng-valkey-$stamp.tar.gz" .
docker compose start

sudo chown "$USER":"$USER" backups/*"$stamp"*
chmod 600 backups/*"$stamp"*
sha256sum backups/*"$stamp".tar.gz > "backups/searxng-$stamp.sha256"

The configuration archive contains SEARXNG_SECRET, so encrypt all three archives and copy them off the VPS. Back up Caddy’s caddy-data volume too if you want to preserve its certificate state, and steer clear of docker compose down -v around these volumes; the -v flag deletes them.

Rehearse an isolated same-version restore

Use a disposable VPS when possible. The same-host drill below uses timestamped names for its directory, network, containers, and volumes, never joins the production Caddy, and starts the same image versions that produced the backup. Keep the commands and the later cleanup in one shell.

cd /opt/searxng
config_archive=$(ls -1 /opt/searxng/backups/searxng-config-*.tar.gz | sort | tail -n 1)
backup_stamp=$(basename "$config_archive" .tar.gz)
backup_stamp=${backup_stamp#searxng-config-}
sha256sum -c "backups/searxng-$backup_stamp.sha256"

restore_id="$(date +%Y%m%d%H%M%S)"
restore_dir="/opt/searxng-restore-$restore_id"
sudo install -d -m 700 -o "$USER" -g "$USER" "$restore_dir"
cd "$restore_dir"
tar -xzf "$config_archive"
docker network create "searxng-restore-$restore_id"
docker volume create "searxng-restore-core-$restore_id"
docker volume create "searxng-restore-valkey-$restore_id"

docker run --rm -v "searxng-restore-core-$restore_id:/restore" \
  -v /opt/searxng/backups:/backup:ro \
  alpine:3.22 \
  tar -C /restore -xzf "/backup/searxng-core-$backup_stamp.tar.gz"
docker run --rm -v "searxng-restore-valkey-$restore_id:/restore" \
  -v /opt/searxng/backups:/backup:ro \
  alpine:3.22 \
  tar -C /restore -xzf "/backup/searxng-valkey-$backup_stamp.tar.gz"

docker run -d --name "searxng-restore-valkey-$restore_id" \
  --network "searxng-restore-$restore_id" --network-alias valkey \
  -v "searxng-restore-valkey-$restore_id:/data" \
  valkey/valkey:9-alpine \
  valkey-server --save 30 1 --loglevel warning

docker run -d --name "searxng-restore-core-$restore_id" \
  --network "searxng-restore-$restore_id" \
  --env-file .env -e SEARXNG_BASE_URL=http://127.0.0.1:18080/ \
  -p 127.0.0.1:18080:8080 \
  -v "$PWD/core-config:/etc/searxng" \
  -v "searxng-restore-core-$restore_id:/var/cache/searxng" \
  searxng/searxng:2026.7.13-9e25585ae

docker logs --tail=50 "searxng-restore-core-$restore_id"

Tunnel port 18080, open the restored instance, and run a real search. Verify customized engines and cached data. The drill omits Caddy on purpose, so it proves data and basic function recovery only; it cannot validate Basic authentication, the trusted-proxy chain, or per-client limiter behavior. Remove the test resources when finished:

docker rm -f "searxng-restore-core-$restore_id" "searxng-restore-valkey-$restore_id"
docker volume rm "searxng-restore-core-$restore_id" "searxng-restore-valkey-$restore_id"
docker network rm "searxng-restore-$restore_id"
sudo rm -r "$restore_dir"

Update images and templates separately

For an image update, back up and restore-test first, review the upstream commit, and bump the SearXNG tag. Change Valkey or Caddy only when you mean to update them. Then redeploy:

cd /opt/searxng
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose logs --tail=100 core valkey caddy

Repeat the Valkey, TLS, browser-like search, and limiter checks. Keep the previous image set and backup together; a safe rollback restores both rather than assuming newer data is backward compatible.

Template maintenance is a separate review. SearXNG’s official instructions may change service names, environment defaults, mounts, or Valkey options without changing your pinned image. Compare the current container/docker-compose.yml, .env.example, settings.template.yml, and searx/limiter.toml in the core repository with your local files. Avoid overwriting .env, settings.yml, or limiter.toml blindly, because that can replace the secret or discard your local proxy controls.

Choosing a Riven Cloud VPS for SearXNG

For a personal or small-team instance, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) runs this whole stack comfortably. All plans come with a 1 Gbps port and full root access; our VPS are unmanaged, so you run the stack yourself and keep full control over it. If you enable many engines, serve several authenticated users, or proxy a lot of images, Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) gives the cache and transfer more headroom.

We offer Tokyo and Singapore. Pick the location that reaches both you and your upstream engines well. If you are on a mainland China network, test the Tokyo Looking Glass and Singapore Looking Glass from your own carrier at the hours you actually search; the two cities can behave quite differently. Current specs and prices are on the Riven Cloud VPS plans page.

Every plan includes daily provider-side backups, and they make a good safety net. They can catch Valkey and the other volumes at different write points, though, so keep the stopped archives, the protected secret, and the encrypted off-server copies above as your primary recovery path.

Security limits and non-fit cases

SearXNG has no built-in login of its own, which is why this deployment leans on Caddy Basic authentication. Test the logged-out denial as well as authenticated assets and form posts, keep the limiter enabled, patch all three images, watch logs and transfer, and keep Valkey off the public Internet. And please leave the Basic auth in place: an unauthenticated instance is open to the whole Internet, draws abuse traffic quickly, and runs against our AUP. The limiter slows bots down, but it is not a substitute for authentication.

Self-hosting is not the right fit for every case, and that is worth being honest about. If you need contractual availability, abuse handling, stable engine coverage, or a guaranteed clean exit reputation, a managed search product will serve you better. The same goes when upstream CAPTCHAs and IP blocks are unacceptable, when users need strong anonymity against traffic correlation, or when nobody has time to keep the limiter rules and restore drills current. SearXNG improves what upstream engines learn about you; it does not make searches invisible to them.

The deployment below runs changedetection.io 0.55.8 on a Debian or Ubuntu VPS. Caddy terminates HTTPS at change.example.com; the application itself listens only on 127.0.0.1:5000.

The install itself is only a few files. The ongoing work, and where this guide spends most of its time, is deciding what the service may reach and making sure its data can actually be restored. A good rule of thumb: use the smallest fetcher that can monitor the target, and remember that every watch URL is a network request your server makes on someone’s behalf.

Prepare the VPS, DNS, and firewall

You need a VPS with root or sudo access, an A record for change.example.com, an AAAA record only when IPv6 works end to end, and encrypted backup storage outside the VPS. TCP 80 and 443 must reach Caddy. Keep your administrative SSH port open, and leave TCP 5000 closed in UFW and the provider firewall; Caddy reaches the application over loopback.

Install Docker Engine and the Compose plugin with Docker’s convenience script (inspect it first if that worries you; on a tightly managed host, use your distribution’s packages instead):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo bash get-docker.sh
sudo docker compose version
sudo apt update
sudo apt install -y caddy jq ufw

That version check aside, the rest of this guide runs docker without sudo, so either add your user to the docker group (sudo usermod -aG docker $USER, then log out and back in) or prefix the docker commands with sudo.

This firewall example assumes SSH listens on port 22. Change that rule before enabling UFW if your server uses another port.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Apply the same inbound policy at the hosting-provider firewall, and confirm the domain resolves to this server with getent ahosts change.example.com.

Create the Docker Compose project

The official 0.55.8 Compose file uses one application container, a named volume at /datastore, and the correct loopback port binding. Keep that architecture for the baseline deployment.

sudo install -d -m 750 -o "$USER" -g "$USER" /opt/changedetection
cd /opt/changedetection
umask 077

Create /opt/changedetection/compose.yml:

services:
  changedetection:
    image: ghcr.io/dgtlmoon/changedetection.io:0.55.8
    container_name: changedetection
    hostname: changedetection
    environment:
      BASE_URL: "https://change.example.com"
      USE_X_SETTINGS: "1"
      LLM_FEATURES_DISABLED: "true"
      HIDE_REFERER: "true"
      TZ: "UTC"
    volumes:
      - changedetection-data:/datastore
    ports:
      - "127.0.0.1:5000:5000"
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    restart: unless-stopped

volumes:
  changedetection-data:

BASE_URL gives notifications the public HTTPS origin. USE_X_SETTINGS=1 lets the application honor proxy host and scheme headers. That setting is safe here because Docker accepts port 5000 only from the VPS loopback path and Caddy controls the forwarded headers. Do not combine it with a public 0.0.0.0:5000 binding.

LLM_FEATURES_DISABLED=true prevents watched content and diffs from being sent to an LLM provider through the application’s AI features. HIDE_REFERER=true applies a referrer policy so monitored sites do not learn the changedetection.io hostname when an operator follows a link. Neither setting makes stored watch data public-safe.

Validate and start the service:

cd /opt/changedetection
docker compose config --quiet
docker compose up -d
docker compose logs --tail=50 changedetection
sudo ss -lntp | grep ':5000'

The listener must show 127.0.0.1:5000, never 0.0.0.0:5000 or [::]:5000.

Set the password before public exposure

changedetection.io is not a multi-user application with a first-account wizard. A default installation has no password. The official password documentation instructs operators to set one in Settings.

Leave Caddy unconfigured. From your workstation, open an SSH tunnel and keep it running:

ssh -N -L 5000:127.0.0.1:5000 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:5000, open Settings, set a strong unique password, and save. Sign out, reload the page, and confirm the password is required and works. This order prevents an Internet visitor from choosing or bypassing the initial protection.

If the password is ever lost, follow the upstream reset procedure but use this deployment’s real container name, changedetection. Reset access only from an authenticated administrative session, then set a new password immediately.

Add Caddy only after the password works

Create a tiny test resource on the same HTTPS origin. It gives the later watch test a URL you control rather than making a third-party site part of service health.

sudo install -d -m 750 -o root -g caddy /srv/changedetection-test
printf '%s\n' 'changedetection test version 1' | \
  sudo tee /srv/changedetection-test/probe.txt > /dev/null
sudo chown root:caddy /srv/changedetection-test/probe.txt
sudo chmod 640 /srv/changedetection-test/probe.txt

Keep the site in an imported snippet so it does not replace any existing Caddy hosts:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/changedetection.caddy > /dev/null <<'CADDY'
change.example.com {
    handle /changedetection-probe.txt {
        root * /srv/changedetection-test
        rewrite * /probe.txt
        file_server
    }

    handle {
        reverse_proxy 127.0.0.1:5000
    }
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsS https://change.example.com/changedetection-probe.txt

Caddy’s automatic HTTPS obtains and renews the certificate when DNS and ports 80/443 are correct. The public root should now show the password-protected application.

Verify system information and a real change

Find the API key under Settings > API. The official API authenticates requests with the x-api-key header. Read the key without adding it to shell history:

read -rsp 'changedetection.io API key: ' CD_API_KEY
printf '\n'
export CD_API_KEY
export CD_URL='https://change.example.com'

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/systeminfo" | jq

Confirm that version is 0.55.8 and review queue_size, overdue_watches, uptime, and watch_count.

Create a watch using the default html_requests fetcher, trigger it, and wait for the first snapshot:

probe="$CD_URL/changedetection-probe.txt"
watch_uuid=$(curl -fsS -X POST "$CD_URL/api/v1/watch" \
  -H "x-api-key: $CD_API_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg url "$probe" \
    '{url:$url,title:"Controlled Compose test",fetch_backend:"html_requests"}')" \
  | jq -er '.uuid')

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid?recheck=true"

for attempt in $(seq 1 24); do
  watch_json=$(curl -fsS -H "x-api-key: $CD_API_KEY" \
    "$CD_URL/api/v1/watch/$watch_uuid")
  if [ "$(jq -r '.last_checked // 0' <<<"$watch_json")" -gt 0 ]; then
    jq '{last_checked,last_error,history_n,fetch_backend}' <<<"$watch_json"
    break
  fi
  sleep 5
done

Change the controlled file, trigger another check, and wait until the API reports at least two snapshots:

printf '%s\n' 'changedetection test version 2' | \
  sudo tee /srv/changedetection-test/probe.txt > /dev/null
sudo chown root:caddy /srv/changedetection-test/probe.txt
sudo chmod 640 /srv/changedetection-test/probe.txt

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid?recheck=true"

for attempt in $(seq 1 24); do
  history_count=$(curl -fsS -H "x-api-key: $CD_API_KEY" \
    "$CD_URL/api/v1/watch/$watch_uuid/history" | jq 'length')
  [ "$history_count" -ge 2 ] && break
  sleep 5
done

curl -fsS -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid/difference/previous/latest?format=text"
curl -fsS -X DELETE -H "x-api-key: $CD_API_KEY" \
  "$CD_URL/api/v1/watch/$watch_uuid" > /dev/null
unset CD_API_KEY

The diff must show the change from version 1 to version 2. One pass through this test exercises DNS, TLS, authentication, queueing, outbound HTTP, snapshot persistence, and diff generation.

Back up the stopped datastore

/datastore holds watches, history, snapshots, headers, notification URLs, browser steps, and application secrets. An archive of it may contain credentials or tokens, so give it mode 600, encrypt it, and copy it off the VPS.

Stop the container first so nothing writes mid-archive, then tar the volume from a helper container:

cd /opt/changedetection
umask 077
install -d -m 700 backups
datastore_volume=$(docker inspect -f \
  '{{range .Mounts}}{{if eq .Destination "/datastore"}}{{.Name}}{{end}}{{end}}' \
  changedetection)
archive="backups/changedetection-$(date +%F-%H%M%S).tar.gz"

docker compose stop changedetection
docker run --rm \
  -v "$datastore_volume:/datastore:ro" \
  -v "$PWD/backups:/backup" \
  alpine:3.22 \
  tar -C /datastore -czf "/backup/$(basename "$archive")" .
docker compose start changedetection

sudo chown "$USER":"$USER" "$archive"
chmod 600 "$archive"
tar -tzf "$archive" > /dev/null
sha256sum "$archive" > "$archive.sha256"

Keep compose.yml, the Caddy configuration, and the checksum alongside the archive in encrypted backup storage.

Rehearse an isolated same-version restore

Restore into a throwaway environment rather than over production. The drill below builds a throwaway volume, network, and container with a timestamped name and starts the same 0.55.8 image that produced the backup. Keep the commands and the later cleanup in one shell:

cd /opt/changedetection
BACKUP=$(ls -1 backups/changedetection-*.tar.gz | sort | tail -n 1)
sha256sum -c "$BACKUP.sha256"

restore_id="changedetection-restore-$(date +%Y%m%d%H%M%S)"
docker volume create "$restore_id"
docker network create --internal "$restore_id"

docker run --rm \
  -v "$restore_id:/datastore" \
  -v "$PWD/backups:/backup:ro" \
  alpine:3.22 \
  tar -C /datastore -xzf "/backup/$(basename "$BACKUP")"

docker run -d --name "$restore_id" \
  --network "$restore_id" \
  -p 127.0.0.1:15000:5000 \
  -v "$restore_id:/datastore" \
  ghcr.io/dgtlmoon/changedetection.io:0.55.8
docker logs --tail=50 "$restore_id"

Tunnel port 15000, log in with the restored password, inspect a few watches and their histories, and run the API system-information check against the restored copy. The internal Docker network blocks scheduled fetches and notification callbacks from leaving the test environment, so fetch errors are expected. Do not connect optional browser automation to production credentials during a recovery drill. Remove the test resources when finished:

docker rm -f "$restore_id"
docker volume rm "$restore_id"
docker network rm "$restore_id"

Upgrade with a recovery point

Read the release notes, take a fresh cold backup, and rehearse its restore. Then bump the version tag in compose.yml and redeploy:

cd /opt/changedetection
docker compose config --quiet
docker compose pull changedetection
docker compose up -d
docker compose logs --tail=100 changedetection

Repeat /api/v1/systeminfo and the two-version watch test. Keep the previous image tag and archive until those checks pass. If an upgrade migrates stored data, rollback means restoring the old image and its pre-upgrade /datastore together. Changing the image tag back on its own may leave migrated data in an unsupported state.

Add a browser only for sites that require it

The baseline deliberately uses the pure HTTP html_requests fetcher. It consumes less memory, does not execute target JavaScript, and stays within changedetection.io’s request-fetching path. Dynamic pages may require the optional Playwright-compatible Sockpuppetbrowser service shown in the official Compose file.

Treat that as a separate change. The upstream example at the time of writing uses dgtlmoon/sockpuppetbrowser:latest and may add SYS_ADMIN; its own comment says that capability may be excessive. Pin a specific browser tag, test whether it runs without the capability, set CPU, memory, process, and screenshot limits, and publish neither its port 3000 nor a VNC port.

Place only changedetection.io and the browser on a dedicated Docker bridge. Private Docker networking prevents a public control port, but it does not restrict outbound destinations. Apply host or provider egress rules that deny cloud metadata, loopback, link-local, RFC1918, management, and storage networks while allowing the explicit container-to-container browser endpoint. Review those rules after every network change.

As of 0.55.8, changedetection.io blocks IANA-restricted addresses by default, rechecks DNS at fetch time, validates every redirect hop, and rejects file:// URLs, with defenses against DNS rebinding and URL-parser tricks; the ALLOW_IANA_RESTRICTED_ADDRESSES and ALLOW_FILE_URI switches both default to false. Resist the temptation to set ALLOW_IANA_RESTRICTED_ADDRESSES=true just to watch a NAS on your LAN. That global opt-in turns private addresses into valid targets for every permitted watch and makes stolen application access far more damaging. Browser traffic also needs network-layer controls because a full browser is not equivalent to the plain-request SSRF filter.

Those controls include fixes covered by the project’s SSRF security advisory. They reduce exposure in the supported configuration; they are not a reason to remove egress filtering or grant watch creation to untrusted users.

Choosing a Riven Cloud VPS for changedetection.io

For a personal watch list on the plain HTTP fetcher, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable starting point. Every plan ships with a 1 Gbps port and full root access. These are unmanaged VPS, which means the stack is yours to run and yours to control. If you add browser workers, keep long snapshot histories, or watch many pages at short intervals, step up to Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) for the extra memory and disk.

We offer Tokyo and Singapore. Pick the location that reaches both you and the sites you monitor well; a server close to your dashboard can still be far from a monitored origin. If you are on a mainland China network, the Tokyo Looking Glass and Singapore Looking Glass let you test real routes from your own connection before ordering. Current specs and prices are on the Riven Cloud VPS plans page.

Daily provider-side backups come with every plan and are a welcome safety net. Treat them as secondary, though: they can catch the application mid-write and they sit inside our recovery system, so the stopped /datastore archive, the encrypted off-server copy, and the restore drill above remain your primary recovery path.

Security limits and non-fit cases

A few habits keep the deployment healthy: keep the application password unique, protect API keys and notification tokens, review who can add watch URLs, and keep an eye on disk growth. Hiding the referrer does not make a fetch anonymous; the target still sees the VPS source IP, timing, request headers, and behavior, so be a polite client and respect site terms, robots policies where applicable, and sensible request rates.

Self-hosting is not always the right call, and that is fine. If nobody will own updates, outbound access policy, alert delivery, backups, and restore tests, the hosted changedetection.io service or another managed monitor will serve you better. A single VPS also cannot usefully monitor its own availability or network path, so give that job to an independent external monitor. And think twice when untrusted tenants can create arbitrary watches, when browser automation needs powerful access to internal systems, or when monitoring credentials call for formal secret management and audit controls.

This tutorial deploys Forgejo 16.0.0, the current release when this article was checked on July 17, 2026, on a fresh Debian or Ubuntu VPS. It uses the standard rootful Docker image and SQLite. Caddy terminates HTTPS for git.example.com, the web listener stays on 127.0.0.1:3000, and Git SSH uses public host port 2222. The path includes an actual clone, commit, and push rather than stopping when the dashboard loads.

SQLite suits a straightforward forge with low-to-moderate activity. Choose PostgreSQL before launch if you expect high concurrency or already operate it well. Changing databases also changes the backup and restore procedure.

Forgejo is one of ten projects in our broader guide to self-hosted apps for a VPS. That guide compares the candidates; this article covers the full deployment path for one of them.

Prerequisites

Prepare the following:

• a Debian or Ubuntu VPS with sudo or root access;
• an A record for git.example.com pointing to the VPS, and an AAAA record only when IPv6 is configured correctly;
• TCP 80 and 443 for the web proxy, TCP 2222 for Forgejo Git SSH, and your separate administrative SSH port;
• Git and an SSH client on your workstation;
• off-server storage large enough for repositories, SQLite, configuration, LFS objects, packages, and attachments.

Harden administrative access first with the secure SSH guide. This tutorial assumes the host’s own SSH daemon remains on port 22, so Forgejo can use 2222 without a collision. If you moved your administrative sshd to 2222, for example by following that guide’s worked example, pick a different host port for Forgejo’s Git SSH, such as 2223, and use it consistently in every firewall rule, port mapping, and clone URL below.

Install Docker Engine and the Compose plugin using Docker’s convenience script (read through it first if you want to see what it will change):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo docker version

Because the script runs as root and adds Docker’s package repository, hosts with stricter policies should install Docker from the distribution’s packages instead. As of July 2026, Forgejo’s upgrade documentation requires Docker 20.10.6 or newer, which the version output confirms.

Install Caddy, Git, and UFW from the distro repository. See Caddy’s official package instructions if your distribution needs its upstream repository.

sudo apt update
sudo apt install -y caddy git ufw

Set the firewall before starting the forge:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 2222/tcp
sudo ufw enable

Replace 22 if your administrative SSH listener uses another port. Mirror these rules in the provider’s cloud firewall or security group. Do not open port 3000 or a database port publicly.

Create the Forgejo deployment

The standard image stores its state under /data. Create a host directory owned by the UID and GID used in the Compose file:

sudo install -d -m 750 -o 1000 -g 1000 /opt/forgejo/forgejo
cd /opt/forgejo

Create /opt/forgejo/compose.yml. The layout follows Forgejo’s official Docker and configuration documentation; the release pin, loopback web binding, public port 2222, disabled registration, and log limits are choices made for this tutorial.

sudo tee compose.yml > /dev/null <<'YAML'
services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:16.0.0
    container_name: forgejo
    restart: unless-stopped
    environment:
      USER_UID: "1000"
      USER_GID: "1000"
      FORGEJO__server__DOMAIN: "git.example.com"
      FORGEJO__server__ROOT_URL: "https://git.example.com/"
      FORGEJO__server__SSH_DOMAIN: "git.example.com"
      FORGEJO__server__SSH_PORT: "2222"
      FORGEJO__service__DISABLE_REGISTRATION: "true"
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "127.0.0.1:3000:3000"
      - "2222:22"
    logging:
      options:
        max-size: "10m"
        max-file: "3"
YAML

The image is pinned to the exact release checked for this article. An exact tag prevents an unattended major migration, but it also stops automatic fixes, so read the canonical Forgejo releases and update the tag deliberately later.

Forgejo converts variables named FORGEJO__[SECTION]__[KEY] into app.ini settings. ROOT_URL controls browser links and HTTPS clone URLs. SSH_DOMAIN and SSH_PORT make displayed SSH clone URLs use git.example.com:2222, while Docker forwards that host port to port 22 inside the standard container.

The ./forgejo:/data mount contains app.ini, repositories, the SQLite database, LFS objects, attachments, packages, SSH-related state, and generated secrets. In particular, losing [security].SECRET_KEY can make encrypted data such as 2FA secrets unreadable.

This guide uses the standard image. It does not teach the rootless variant because its paths and port mappings differ. Validate those details against the exact image before designing a rootless deployment.

Start the service, wait for the web listener, then confirm port 3000 is loopback-only and port 2222 is public:

cd /opt/forgejo
sudo docker compose up -d
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Forgejo did not become ready within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done
sudo ss -lntp | grep -E ':(3000|2222)'

Add Caddy and HTTPS

Use a dedicated subdomain. Forgejo’s reverse-proxy documentation warns against putting a forge below a subpath on an origin that also serves user-controlled content because same-origin and CSRF boundaries become harder to protect.

Create an imported Caddy site snippet. This keeps existing hosts intact even when Forgejo is not the first service on the VPS:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/forgejo.caddy > /dev/null <<'CADDY'
git.example.com {
    reverse_proxy 127.0.0.1:3000
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy requests and renews the certificate when DNS and both firewalls permit TCP 80/443. Git SSH does not pass through Caddy. Clients connect directly to port 2222.

Complete the first-run installer

An uninitialized public forge can be claimed by whoever reaches its installer first. Open https://git.example.com only when you are ready to finish setup. For stricter staging, keep Caddy stopped and tunnel the loopback listener with ssh -L 3000:127.0.0.1:3000 root@SERVER_IP, then browse to http://127.0.0.1:3000.

In the installer:

1. Select SQLite3 and keep its database inside /data.
2. Confirm the server domain is git.example.com.
3. Confirm the Forgejo base URL is https://git.example.com/.
4. Confirm the SSH domain is git.example.com and the SSH port is 2222.
5. Expand the administrator section and create the first administrator with a strong unique password and a real email address.
6. Finish the installation and sign in.

The first user created during installation receives administrator access. Registration is already disabled through Compose. Verify that a logged-out visitor cannot register, then enable 2FA on the administrator account. Configure SMTP before depending on password reset, email confirmation, or notifications.

Verify HTTPS and SSH Git workflows

Run the server-side checks:

cd /opt/forgejo
curl -fsSI https://git.example.com/
sudo docker compose exec forgejo \
  forgejo doctor check --all --log-file /tmp/doctor.log
sudo docker compose exec forgejo cat /tmp/doctor.log

In the web UI, create a disposable repository named docker-test under your account. Leave it empty for the first clone. Forgejo’s HTTP clone path uses HTTPS here, so credentials and repository data are protected in transit. On your workstation, replace YOUR_USER with the account name:

git clone https://git.example.com/YOUR_USER/docker-test.git
cd docker-test
git config user.name "Forgejo Test"
git config user.email "forgejo-test@example.com"
printf '%s\n' 'Forgejo end-to-end test' > README.md
git add README.md
git commit -m "Test HTTPS push"
git branch -M main
git push -u origin main

Enter the Forgejo username and password or personal access token when Git prompts. Refresh the browser and confirm the commit and file appear. This proves that the reverse proxy, application, SQLite database, and repository storage agree.

Now test SSH. Add your workstation’s public SSH key under Settings > SSH/GPG Keys, then run:

ssh -F /dev/null -p 2222 git@git.example.com

Forgejo should recognize the account and deny interactive shell access. Change the existing clone to SSH and push a second commit:

git remote set-url origin \
  ssh://git@git.example.com:2222/YOUR_USER/docker-test.git
printf '%s\n' 'SSH push works' >> README.md
git add README.md
git commit -m "Test SSH push"
git push

Confirm the second commit in the web UI. Delete the disposable repository after the backup test if you do not need it.

Plan for storage and runners

Git history is only part of forge storage. Git LFS, release attachments, package registries, repository mirrors, and Actions artifacts can grow independently. Set quotas where appropriate and monitor the filesystem instead of estimating capacity from repository count.

Run Forgejo Actions runners as separate services with their own lifecycle and isolation. Workflow code may be controlled by repository contributors. Do not attach a runner to the Forgejo container or casually give it the host Docker socket; that can turn a CI job into host-level access. Follow the project’s separate Actions security documentation before enabling untrusted workflows.

Back up and rehearse restoration

Forgejo’s official guidance requires a synchronized point-in-time copy of every storage component. For this single-volume SQLite design, a stopped-container archive of /data captures the database, repositories, configuration, packages, LFS objects, and generated secrets together:

sudo install -d -m 700 /var/backups/forgejo
cd /opt/forgejo
sudo docker compose exec forgejo forgejo manager flush-queues
sudo docker compose stop forgejo
sudo tar --numeric-owner -C /opt/forgejo -czf \
  "/var/backups/forgejo/forgejo-$(date +%F-%H%M%S).tar.gz" \
  forgejo
sudo docker compose start forgejo
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Forgejo did not restart within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done

Encrypt and copy the archive off-host. If you move to PostgreSQL or MySQL, stop or quiesce Forgejo and take the database vendor’s native dump as part of the same recovery point. External object storage and remote repository paths must be captured with it. forgejo dump can be useful, but the official upgrade guide warns about restoring its SQL output for external databases; do not treat it as a substitute for pg_dump or mysqldump.

Restore onto an isolated test VPS with Forgejo 16.0.0. Transfer one archive, set BACKUP to its real path, and keep the empty directory as a rollback point:

export BACKUP=/path/to/forgejo-YYYY-MM-DD-HHMMSS.tar.gz
cd /opt/forgejo
sudo docker compose stop forgejo
sudo mv forgejo forgejo.empty
sudo tar --numeric-owner -C /opt/forgejo -xzf "$BACKUP"
sudo chown -R 1000:1000 /opt/forgejo/forgejo
sudo docker compose up -d
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Restored Forgejo did not become ready within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done
sudo docker compose exec forgejo \
  forgejo doctor check --all --log-file /tmp/doctor.log
sudo docker compose exec forgejo cat /tmp/doctor.log

Log in, clone the restored docker-test repository over HTTPS, push a commit over SSH, and check any LFS objects, packages, or attachments you use. Upgrade only after the restored copy passes those checks.

Every Riven Cloud plan includes daily provider backups, which make a good extra layer, but they are no substitute for an application-consistent Forgejo backup and a rehearsed restore, so keep both.

Upgrade deliberately

Read the release notes and known upgrade issues, take a consistent backup, then flush queues:

cd /opt/forgejo
sudo docker compose exec forgejo forgejo manager flush-queues

Change 16.0.0 in compose.yml to the reviewed release and run:

sudo docker compose pull
sudo docker compose up -d
for attempt in $(seq 1 24); do
  if curl -fsS -o /dev/null http://127.0.0.1:3000/; then
    break
  fi
  if [ "$attempt" -eq 24 ]; then
    echo "Upgraded Forgejo did not become ready within 120 seconds" >&2
    exit 1
  fi
  sleep 5
done
sudo docker compose exec forgejo \
  forgejo doctor check --all --log-file /tmp/doctor.log
sudo docker compose exec forgejo cat /tmp/doctor.log

Repeat login, HTTPS clone, SSH push, and storage checks. Major upgrades require an explicit tag change and human verification. Forgejo performs database migrations at startup; do not assume a downgrade will be safe after those migrations.

Choosing a Riven Cloud VPS for Forgejo

For a small private forge with ordinary source repositories, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB transfer) is a solid start. Storage is usually the first thing you outgrow: Git LFS, packages, release assets, mirrors, and CI artifacts add up much faster than plain Git history. When they do, Ultra raises the NVMe to 80 GB and transfer to 2 TB, and Max provides 160 GB and 4 TB. Watch retained data and clone traffic rather than sizing by repository count, and keep Actions runners on separately isolated capacity.

All plans include a 1 Gbps port, full root access, daily backups, and deployment in Tokyo or Singapore. Our plans are unmanaged, so you keep full control of the stack you just built. Put the forge near the developers and systems that clone, push, fetch packages, and receive webhooks; teams connecting from mainland China can compare the Tokyo Looking Glass and Singapore Looking Glass from the office or carrier network to see which location feels closer. The pricing page lists the current storage and transfer limits.

Security limits

Keep public registration disabled unless you can handle spam, abuse reports, mail reputation, and user storage. If you open it, use Forgejo’s recommended CAPTCHA and username-cooldown controls. Protect administrator accounts with 2FA, review webhook targets and secrets, and leave local-network access for repository migrations disabled unless you have a specific reason to permit it.

Third-party themes, Git hooks, templates, extensions, and runners execute or influence trusted server-side work. Add them only with a review and backup plan.

When not to self-host

If source availability is business-critical and nobody on the team wants to own upgrades, monitoring, mail, incident response, and restore tests, a managed forge will serve you better. A single VPS may also fall short of compliance or geographic-redundancy requirements. And if you need to run untrusted workflow code but cannot isolate runners from the forge and host, managed CI is the safer choice.

This guide builds that deployment on a Debian or Ubuntu VPS. The application listens only on 127.0.0.1:2586; Caddy or Nginx owns the public ports. We use the official binwiederhier/ntfy:v2.26.0 image, which was the latest release when checked on July 17, 2026, with ntfy’s SQLite storage, the conservative choice for one unmanaged server.

One warning before anything else: ntfy allows anonymous users to read and write every topic by default, and adding an auth-file alone does not make the server private. The configuration below sets auth-default-access: deny-all, then grants access with named users and topic ACLs.

Prerequisites: prepare the VPS, DNS, and firewall

You need a Linux VPS with root or sudo access, a DNS record for ntfy.example.com, and Docker Engine with the Compose plugin. Point an A record at the server’s IPv4 address. Add an AAAA record only if the VPS, firewall, and reverse proxy all serve IPv6.

Our VPS plans are unmanaged, so you run Docker, TLS, the firewall, monitoring, backups, and upgrades yourself and keep full control of the stack. If you want one server for several small services, our self-hosted apps guide can help you decide what belongs on the same VPS.

Install Docker Engine and the Compose plugin. Docker’s convenience script is the quickest way to get both; anyone uneasy about running a downloaded script as root can install from the distribution’s packages instead:

curl -fsSL https://get.docker.com | sudo bash
sudo docker compose version

The rest of the guide assumes your user can run Docker without sudo. Either prefix Docker commands with sudo, or follow Docker’s documented post-install procedure.

Allow SSH before enabling or changing a firewall; if you have not hardened that port yet, our walkthrough of securing SSH on a VPS covers it. If UFW is already active, add only the web ports:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Mirror those rules in any provider firewall. Do not open port 2586 publicly. After DNS propagates, getent ahosts ntfy.example.com should show this VPS.

Create the ntfy Compose project

Keep the project in one directory so its configuration and storage paths remain unambiguous:

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/ntfy
cd /opt/ntfy
umask 077
install -d -m 0700 cache data

Create /opt/ntfy/compose.yaml. The loopback binding, deny-by-default policy, explicit limits, and file permissions are hardening choices on top of ntfy’s official example and configuration reference.

services:
  ntfy:
    image: binwiederhier/ntfy:v2.26.0
    container_name: ntfy
    command: serve
    environment:
      TZ: UTC
    ports:
      - "127.0.0.1:2586:80"
    volumes:
      - ./server.yml:/etc/ntfy/server.yml:ro
      - ./cache:/var/cache/ntfy
      - ./data:/var/lib/ntfy
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '\"healthy\"\\s*:\\s*true' || exit 1",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s
    init: true
    restart: unless-stopped

Create /opt/ntfy/server.yml:

base-url: "https://ntfy.example.com"
behind-proxy: true

cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"

attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "5G"
attachment-file-size-limit: "15M"
attachment-expiry-duration: "3h"
visitor-attachment-total-size-limit: "100M"
visitor-attachment-daily-bandwidth-limit: "500M"

auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"

enable-login: true
require-login: true
enable-signup: false

# Optional for prompt delivery to the official iOS app:
# upstream-base-url: "https://ntfy.sh"

Keep the project files private too:

cd /opt/ntfy
chmod 600 compose.yaml server.yml

The 12-hour message retention and the attachment limits are ntfy’s documented defaults, written out here so you can review them. They are limits, not a sizing recommendation. cache/cache.db and cache/attachments/ hold temporary messages and files. data/user.db is durable security state: users, password hashes, tokens, and ACLs.

Start ntfy and check its health:

docker compose up -d --wait --wait-timeout 120
curl -fsS http://127.0.0.1:2586/v1/health

The response should contain {"healthy":true}.

Create users and topic ACLs

There is no default administrator. Add one interactively; the password is hashed into data/user.db rather than written into Compose:

docker compose exec ntfy ntfy user add --role=admin admin

An administrator can read and write every topic. For automation, a regular account with a narrow ACL is safer. These commands create a publisher that may write, but not read, the backups topic:

docker compose exec ntfy ntfy user add publisher
docker compose exec ntfy ntfy access publisher backups write-only

Create a separate subscriber if a person or service needs read-only access:

docker compose exec ntfy ntfy user add subscriber
docker compose exec ntfy ntfy access subscriber backups read-only
docker compose exec ntfy ntfy access

You can create a client token so scripts never see the account password:

docker compose exec ntfy ntfy token add --expires=90d --label="tutorial-client" publisher

Store the returned token in a secret manager. ntfy tokens inherit the user’s permissions; they have no separate scopes.

Put ntfy behind HTTPS

TLS is required because Basic credentials and bearer tokens must never cross plaintext HTTP. behind-proxy: true also matters: without it, ntfy sees the proxy as every visitor and applies one shared rate-limit bucket.

Caddy’s automatic HTTPS keeps the proxy configuration small. Install Caddy through its official distro instructions, then add this site to /etc/caddy/Caddyfile:

ntfy.example.com {
    reverse_proxy 127.0.0.1:2586
}

Validate and reload it:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Caddy forwards client information and supports WebSocket upgrades by default. For Nginx, use ntfy’s official reverse-proxy example, not a bare proxy_pass: preserve Host, append X-Forwarded-For, set X-Forwarded-Proto, use HTTP/1.1 with Upgrade and Connection, disable response buffering for streaming subscriptions, allow request bodies up to your attachment limit, and set long read and send timeouts. Terminate TLS with a valid certificate on port 443 and redirect port 80 to HTTPS.

Verify the public endpoint:

curl -fsS https://ntfy.example.com/v1/health

Run an end-to-end notification test

First prove that anonymous publishing is blocked:

curl -sS -o /dev/null -w '%{http_code}\n' \
  -d 'anonymous publish should fail' \
  https://ntfy.example.com/backups

The result must not be a 2xx status. A 401 or 403 confirms the private default is in effect.

In the ntfy web app or mobile app, add https://ntfy.example.com as the server, sign in as subscriber, and subscribe to backups. Then publish with the restricted account:

curl -fsS \
  -u 'publisher:YOUR_PASSWORD' \
  -H 'Title: Backup test' \
  -H 'Priority: high' \
  -d 'ntfy end-to-end test' \
  https://ntfy.example.com/backups

Confirm the message appears in the subscribed browser or phone. Polling the API gives a second check:

curl -fsS \
  -u 'subscriber:YOUR_PASSWORD' \
  'https://ntfy.example.com/backups/json?poll=1&since=10m'

Now test persistence within the 12-hour cache window:

docker compose restart ntfy
curl -fsS https://ntfy.example.com/v1/health
curl -fsS -u 'subscriber:YOUR_PASSWORD' \
  'https://ntfy.example.com/backups/json?poll=1&since=10m'

For an attachment test, create a harmless file smaller than 15 MB and upload it:

printf 'attachment persistence test\n' > /tmp/ntfy-test.txt
curl -fsS -u 'publisher:YOUR_PASSWORD' \
  -H 'Filename: ntfy-test.txt' \
  -T /tmp/ntfy-test.txt \
  https://ntfy.example.com/backups
rm /tmp/ntfy-test.txt

The subscriber should receive an attachment link hosted at ntfy.example.com. Treat that URL as a capability link: ntfy’s file handler serves the attachment by message ID, without applying the topic ACL to the download. Anyone who obtains the URL can fetch the file until it expires. Do not send sensitive attachments through this path; use an authenticated object-delivery system when each download must be authorized.

For a harmless test file, download it before the configured three-hour expiry, restart ntfy, and confirm it remains available during that window. ntfy manages the attachment directory and deletes expired or unreferenced files, so never share the directory with another application.

Understand the iOS delivery trade-off

Prompt delivery to the official iOS app requires an APNS-connected upstream, normally https://ntfy.sh. Uncomment upstream-base-url and recreate ntfy if that delivery behavior matters. According to ntfy’s iOS documentation, the upstream receives the message ID and a SHA-256-derived topic identifier, not the message body.

Leaving the setting disabled avoids that upstream dependency, but iOS notifications can be delayed significantly. A self-hosted ntfy server therefore does not promise fully independent, instant iOS push. Android normally keeps an instant-delivery connection to the self-hosted server; using FCM requires a custom app build and Firebase configuration.

Back up and restore ntfy

ntfy has no dedicated backup tool. Stop the container, archive the project directory, and start it again:

cd /opt/ntfy
install -d -m 0700 backups
archive="backups/ntfy-$(date +%F-%H%M%S).tar.gz"

docker compose stop ntfy
sudo tar -czf "$archive" compose.yaml server.yml data cache
sudo chmod 600 "$archive"
docker compose start ntfy
curl -fsS --retry 12 --retry-delay 5 --retry-all-errors \
  http://127.0.0.1:2586/v1/health

data/user.db is the part you cannot lose: it holds accounts, tokens, and ACLs. The message cache and attachments are temporary by design; a minimal backup may omit cache, but document that recovery will then not include recent messages or files.

Encrypt the archive before transferring it off the VPS. File permissions protect it on this host, not at the destination.

To restore, stop ntfy and move the damaged project aside. This example assumes the backup archive is still under the old project’s backups directory; list that directory first and replace the ntfy-YYYY-MM-DD-HHMMSS.tar.gz placeholder below with the real filename, which carries both the date and the time of the backup:

cd /opt/ntfy
docker compose stop ntfy
cd /opt
sudo mv ntfy ntfy.failed
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/ntfy
cd /opt/ntfy
ls /opt/ntfy.failed/backups/
sudo tar -xzf /opt/ntfy.failed/backups/ntfy-YYYY-MM-DD-HHMMSS.tar.gz
sudo chown -R "$USER":"$USER" /opt/ntfy
install -d -m 0700 backups
chmod 700 data cache

docker compose up -d --wait --wait-timeout 120
curl -fsS https://ntfy.example.com/v1/health
docker compose exec ntfy ntfy access

Start the same ntfy version first. Verify an authenticated publish and a cached attachment before upgrading. Do not run docker compose down -v; it is unnecessary here and a dangerous habit around stateful Compose projects.

Every one of our plans includes daily backups, a solid fallback when the entire host needs to come back. Keep the stopped archive, the rehearsed restore, and an encrypted off-server copy in your routine as well; they are what guarantee an application-consistent data/user.db.

Upgrade without losing state

Read the ntfy release notes, take a fresh backup, and change the image tag in compose.yaml only after reviewing the target release. Then run:

docker compose pull ntfy
docker compose up -d --wait --wait-timeout 120
curl -fsS https://ntfy.example.com/v1/health

Repeat the anonymous rejection and authenticated delivery tests. Keep the old archive until the new version has survived a restart and delivered an attachment.

Choosing a Riven Cloud VPS for ntfy

ntfy itself is a light workload. For a private, authenticated server handling alerts from a handful of machines, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is more than enough. Consider Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB transfer) or Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) if you expect many subscribers, long retention, or frequent large attachments. Whichever plan you pick, keep the ACLs and quotas above in place; access control is what keeps transfer and disk usage predictable.

Choose Tokyo or Singapore based on where your publishers and subscribers sit. If clients connect from mainland China, a quick test from the Tokyo Looking Glass and Singapore Looking Glass on your own carrier, at the time of day you care about, will tell you more than any route description. The Riven Cloud VPS plan comparison shows the current NVMe and monthly-transfer limits.

Security limits and when not to self-host

Publicly writable ntfy topics can become notification spam, phishing, attachment hosting, or unexpected VPS transfer. ntfy includes request, subscription, and attachment limits, but those controls do not turn an anonymous service into a private one. Keep deny-all, grant narrow ACLs, protect tokens, monitor logs and disk usage, and patch both Docker and ntfy.

Hosted ntfy or another managed notification service is the better fit when nobody has time to maintain TLS, monitoring, updates, and restore tests; when you need contractual availability or delivery guarantees; or when public anonymous topics are part of the product and running an abuse desk is not realistic. And if dependable iOS push is the hard requirement, be clear-eyed about the trade. With upstream-base-url set, every notification sends a delivery poke through ntfy.sh, though the upstream sees only the message ID and a hashed topic identifier while the content stays on your server. That is a dependency on upstream infrastructure rather than a content leak, but it does mean your alerting is only as available as ntfy.sh; if that dependency is unacceptable and instant iOS delivery is non-negotiable, hosted delivery is the more practical choice.

The container’s Apache listener is available only at 127.0.0.1:8080. Caddy is the public entry point, while the image’s built-in cron runs feed refreshes twice an hour. The verification path adds a real Atom feed, runs the updater, marks an article read, restarts the container, and checks that both the subscription and read state survived.

FreshRSS is one option in our broader guide to self-hosted apps for a VPS. It makes a good first service; just plan on maintaining TLS, updates, and backups after the novelty wears off.

Prerequisites

You need:

• a Debian or Ubuntu VPS with root or sudo access;
• an A record for rss.example.com pointing to the VPS, plus an AAAA record only if IPv6 is configured and filtered correctly;
• TCP 80 and 443 open for Caddy and certificate issuance;
• a modern browser and an off-server backup destination.

The SQLite path in this tutorial is simple and complete for a single VPS. FreshRSS also supports PostgreSQL and MySQL/MariaDB, but either choice adds a separate database service, credentials, upgrades, and backup scope. No public database port is needed.

Secure the host’s administrative login before deploying the reader. Our SSH hardening guide explains how to add and test keys before disabling passwords.

Install Docker Engine and the Compose plugin with Docker’s convenience script (read it first if piping a script into root bothers you, or use Docker’s apt repository instead):

curl -fsSL https://get.docker.com -o get-docker.sh
sudo bash get-docker.sh
sudo docker compose version

Install Caddy and UFW from the Debian or Ubuntu repository. Caddy also publishes official package instructions for distributions that need its upstream repository.

sudo apt update
sudo apt install -y caddy ufw

This firewall example assumes administrative SSH uses TCP 22:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Replace port 22 if you moved SSH. Apply the same public inbound rules to the provider’s cloud firewall or security group. Port 8080 must not be public.

Create the Compose deployment

Store the deployment under /opt/freshrss. Bind mounts make the data and extensions easy to inspect, archive, and restore without relying on Docker’s volume-name conventions.

sudo install -d -m 750 /opt/freshrss
sudo install -d -m 750 /opt/freshrss/data
sudo install -d -m 750 /opt/freshrss/extensions
cd /opt/freshrss

Create /opt/freshrss/compose.yml. It follows FreshRSS’s official Docker examples; the release pin, loopback binding, and staggered cron schedule are our choices.

sudo tee compose.yml > /dev/null <<'YAML'
services:
  freshrss:
    image: freshrss/freshrss:1.29.1
    container_name: freshrss
    restart: unless-stopped
    environment:
      TZ: "UTC"
      CRON_MIN: "13,43"
    volumes:
      - ./data:/var/www/FreshRSS/data
      - ./extensions:/var/www/FreshRSS/extensions
    ports:
      - "127.0.0.1:8080:80"
    logging:
      options:
        max-size: "10m"
        max-file: "3"
    healthcheck:
      test: ["CMD", "cli/health.php"]
      timeout: 10s
      start_period: 60s
      interval: 75s
      retries: 3
YAML

FreshRSS listens on port 80 inside this image. Docker maps it to loopback port 8080, where only host processes such as Caddy can connect. /var/www/FreshRSS/data contains configuration, user data, and the SQLite databases. The extensions mount preserves any third-party extensions installed later.

TZ=UTC makes log and cron times unambiguous. CRON_MIN=13,43 asks the image’s scheduled job to run at 13 and 43 minutes past each UTC hour. The stagger avoids the common top-of-hour spike. FreshRSS’s feed-update documentation notes that scheduling much more often than every 20 minutes brings little benefit because individual feeds are not refreshed more frequently than that.

Pinning 1.29.1 keeps the deployment reproducible. It also requires you to read the FreshRSS release notes and deliberately change the tag when you are ready to update. Avoid the rolling edge tag for a routine production install.

Start the service:

cd /opt/freshrss
sudo docker compose up -d --wait --wait-timeout 120
sudo docker compose logs --tail=50 freshrss

Confirm that Apache is not exposed on every interface:

sudo ss -lntp | grep ':8080'
curl -fsSI http://127.0.0.1:8080/

The listener should show 127.0.0.1:8080, not 0.0.0.0:8080.

Complete the web installer through an SSH tunnel

Do not add the public Caddy route yet. The uninitialized web installer creates the first user, so exposing it before setup gives an Internet visitor a chance to claim the instance. Complete it through a private SSH tunnel instead.

From your workstation, open a tunnel and leave it running:

ssh -N -L 8080:127.0.0.1:8080 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:8080. The official Docker guide recommends the web installation path used here.

1. Choose the interface language and continue after the prerequisite check passes.
2. Select SQLite as the database.
3. Set the application or base URL to https://rss.example.com.
4. Create the initial user with a strong, unique password.
5. Select form authentication and finish the installation.
6. Log in through the tunnel.

Never select No authentication for a reader reachable from the Internet. FreshRSS’s access-control documentation calls that mode dangerous on a public server.

The Compose file contains no administrator password because the browser setup writes it directly into the persistent data directory. The official image also supports unattended environment variables, but those variables apply only during first initialization and make secret handling easier to get wrong.

Before public exposure, confirm the initial user exists:

cd /opt/freshrss
sudo docker compose exec --user www-data freshrss cli/list-users.php

Sign out through the tunneled browser, reload the root page, and visit http://127.0.0.1:8080/i/. The root must show the login flow, and /i/ must not offer a fresh installation wizard. Stop and inspect the persistent data directory if the installer is still available. Close the tunnel only after those checks pass.

Configure Caddy and TLS

Now expose the initialized login page through Caddy. Use an imported site snippet so this tutorial does not overwrite other hosts already served by Caddy:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/freshrss.caddy > /dev/null <<'CADDY'
rss.example.com {
    reverse_proxy 127.0.0.1:8080
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsSI https://rss.example.com/

Caddy obtains and renews a public certificate when DNS points to this VPS and TCP 80/443 can reach it. If the certificate does not appear, check the DNS records, UFW, the provider firewall, and sudo journalctl -u caddy -n 100 --no-pager.

Do not broaden FreshRSS’s TRUSTED_PROXY setting just to make the page load. It affects which forwarded client addresses and authentication headers FreshRSS trusts. This host-proxy design works without adding a broad Docker-network range. If a later authentication integration requires the setting, trust only the actual proxy path.

Add a feed and prove state persists

Log in at https://rss.example.com. Choose Add a feed and enter the public FreshRSS releases feed:

https://github.com/FreshRSS/FreshRSS/releases.atom

Trigger an immediate server-side refresh rather than waiting for minute 13 or 43:

cd /opt/freshrss
sudo docker compose exec --user www-data freshrss \
  php /var/www/FreshRSS/app/actualize_script.php
sudo docker compose logs --since=5m freshrss

Reload the browser and confirm release entries appear. Open one item, mark it read, and optionally mark it as a favorite. Then restart the container:

sudo docker compose restart freshrss
sudo docker compose exec --user www-data freshrss cli/health.php

Log in again. The subscription, its articles, and the read or favorite state should all have survived, which exercises the browser workflow, updater, SQLite data, and bind mount together. After minute 13 or 43 passes, check sudo docker compose logs --since=45m freshrss to confirm cron ran.

If you use a mobile reader, enable API access in the user settings and set a separate API password. Test login and article-state sync from that client. Do not assume the normal web password is the API credential.

Use OPML for migration, not recovery

FreshRSS can import and export subscriptions as OPML from Subscription management > Import/export. Export an OPML file after initial setup and whenever the subscription list changes substantially. It is useful for moving feeds to another reader or rebuilding the list by hand.

OPML is not a full backup. It does not preserve the whole FreshRSS configuration, read and favorite state, user credentials, extensions, or every feed-specific setting. Keep it beside, not instead of, the application backup.

Back up data, SQLite, and extensions

FreshRSS’s backup guide provides a portable per-user SQLite export:

cd /opt/freshrss
sudo docker compose exec --user www-data freshrss cli/db-backup.php

The command writes the export under persistent user data, so it still needs to be copied off the server. For full state, archive both bind mounts with the container stopped:

sudo install -d -m 700 /var/backups/freshrss
cd /opt/freshrss
sudo docker compose stop freshrss
sudo tar -C /opt/freshrss -czf \
  "/var/backups/freshrss/freshrss-$(date +%F-%H%M%S).tar.gz" \
  data extensions
sudo docker compose up -d --wait --wait-timeout 120

Encrypt the archive and copy it to storage outside the VPS. If you adopt PostgreSQL or MySQL/MariaDB, include a native pg_dump or mysqldump from the same recovery point.

Test the archive on an isolated VPS with the same image tag. Transfer one archive, set BACKUP to its real path, and keep the empty directories as rollback points:

export BACKUP=/path/to/freshrss-YYYY-MM-DD-HHMMSS.tar.gz
cd /opt/freshrss
sudo docker compose stop freshrss
sudo mv data data.empty
sudo mv extensions extensions.empty
sudo tar -C /opt/freshrss -xzf "$BACKUP"
sudo docker compose up -d --wait --wait-timeout 120
sudo docker compose exec --user www-data freshrss cli/health.php

Log in, refresh the test feed, and confirm the subscription and read state. Test each installed extension too.

For a portable database export, the official restore command is:

sudo docker compose exec --user www-data freshrss \
  cli/db-restore.php --delete-backup --force-overwrite

Use it only against the intended test or recovery instance after reading the prompts and backup documentation.

Every Riven Cloud plan includes daily backups, and they make a good safety net, but they do not replace an application-consistent backup and a rehearsed restore.

Upgrade the container

Read the release notes, export the user database, and take the stopped-container archive. Change only the exact image tag in compose.yml, then run:

cd /opt/freshrss
sudo docker compose pull
sudo docker compose up -d --wait --wait-timeout 120
sudo docker compose exec --user www-data freshrss cli/health.php

Log in, run /var/www/FreshRSS/app/actualize_script.php, and confirm feed and read-state behavior. Docker deployments should replace the image rather than use the web updater. Treat a PostgreSQL major-version change as a separate database migration.

Choosing a Riven Cloud VPS for FreshRSS

For a private reader on SQLite, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable fit. Feed count, refresh frequency, full-text retrieval, and retention decide how far it stretches; if you add PostgreSQL, RSS-Bridge, heavy image proxying, or browser-based scraping, our Ultra plan (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB) is the sensible step up. Every plan is an unmanaged KVM VPS with full root access, a 1 Gbps port, and daily backups, so you run the stack yourself and keep full control.

FreshRSS talks both to its readers and to feed publishers, so location affects two paths. Choose Tokyo or Singapore based on where you read from, and check that your important feeds respond well from that data-center IP (more RAM will not fix a publisher that blocks data-center traffic). If you read from mainland China, a quick comparison of the Tokyo Looking Glass and Singapore Looking Glass from your own access network will show which location feels faster. Once you have a rough idea of the workload, the details are on the Riven Cloud VPS plans page.

Security limits

FreshRSS fetches user-supplied feed URLs from the server, which creates server-side request forgery risk on shared or multi-user instances. As of July 16, 2026, release 1.29.1 does not restrict fetching internal hosts, so a feed URL can reach loopback or LAN services the container can route to. Rely on network-level controls instead: the compose and network layout in this guide, the firewall, and keeping cloud metadata endpoints and sensitive internal services out of the container’s reach. The next release after 1.29.1 adds default internal-host blocking with an INTERNAL_HOST_ALLOWLIST allowlist (FreshRSS PR #8400), so revisit this section after upgrading; at that point, allow only the exact host, port, or network range a private RSS-Bridge or RSSHub needs, and never set the allowlist to *.

Install extensions only from sources you trust because they execute server-side code. Protect private feed URLs, feed credentials, browser sessions, and backups. Keep Apache’s port on loopback and apply host and container updates promptly.

When not to self-host

A hosted reader is the better choice if nobody will own TLS, feed scheduling, updates, monitoring, and restore tests. A public reader for untrusted users also brings SSRF, privacy, abuse, and transfer concerns that a personal instance largely avoids, and a managed service is the safer fit when private feed credentials need formal controls or reader availability needs a commercial SLA.

This tutorial installs the current Umami 3.2.0 release on Debian or Ubuntu with Docker Compose. Umami listens only on 127.0.0.1:3000; PostgreSQL has no host port at all. Caddy or Nginx terminates TLS at analytics.example.com.

This deployment pins the application image to ghcr.io/umami-software/umami:3.2.0, the newest release when checked on July 16, 2026. Umami publishes plain version tags on GHCR (3, 3.2, 3.2.0, and so on) alongside latest, so pinning the exact release keeps upgrades deliberate instead of accidental. The database follows the official Compose file’s choice of postgres:15-alpine.

Prerequisites: prepare Docker, DNS, and the firewall

You need an unmanaged Linux VPS with root or sudo access, Docker Engine, the Compose plugin, and a DNS A record that points analytics.example.com to the VPS. Publish an AAAA record only when the complete HTTPS path works over IPv6. Umami requires PostgreSQL 12.14 or newer; this deployment follows the official Compose choice of the PostgreSQL 15 Alpine series and configures it for UTC.

Our VPS plans are unmanaged, so you run the containers, database, firewall, backups, and upgrades yourself and keep full control. If you are comparing several services for one server, our self-hosted apps guide is a good place to start.

Install Docker Engine and the Compose plugin with Docker’s convenience script; it is worth skimming the script before running it so you know what it changes:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo docker compose version

The script runs as root and adds Docker’s package repository. If that does not suit your host, use your distribution’s own Docker packages instead. The commands below assume your user can run Docker. Otherwise prefix them with sudo or follow Docker’s documented post-install procedure.

If UFW is active, allow HTTP and HTTPS. Keep the current SSH rule in place:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw status

Apply equivalent rules at the hosting-provider firewall. Do not expose ports 3000 or 5432. Confirm DNS with getent ahosts analytics.example.com before requesting a certificate.

Generate the environment file

Create the project directory:

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/umami
cd /opt/umami

Generate URL-safe random values without printing them to the terminal. Hex keeps the PostgreSQL password valid inside DATABASE_URL without percent-encoding:

umask 077
printf 'POSTGRES_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
printf 'APP_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
chmod 600 .env

Do not paste the contents of .env into tickets or logs. DATABASE_URL tells Umami which PostgreSQL user, password, database, host, and port to use. In Compose, the hostname is the service name db, not localhost. APP_SECRET is a unique random value used to secure authentication tokens. Keep it unchanged across restarts and restores; changing it invalidates existing login sessions.

Create the Umami and PostgreSQL services

Create /opt/umami/compose.yaml. It is based on Umami’s official Compose file; the loopback-only publication, required APP_SECRET, and bounded health waits are choices made for this tutorial.

services:
  umami:
    image: ghcr.io/umami-software/umami:3.2.0
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: "postgresql://umami:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/umami"
      APP_SECRET: "${APP_SECRET:?set APP_SECRET}"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test:
        ["CMD-SHELL", "curl -fsS http://localhost:3000/api/heartbeat || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 6
      start_period: 30s
    init: true
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}"
      TZ: UTC
      PGTZ: UTC
    volumes:
      - umami-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 6
    restart: unless-stopped

volumes:
  umami-db-data:

The db health check prevents Umami from starting before PostgreSQL accepts connections. All accounts, website definitions, shares, and analytics events live in the named umami-db-data volume. The application container is disposable and needs no data volume.

Start both services and check the heartbeat:

docker compose up -d --wait --wait-timeout 180
curl -fsS http://127.0.0.1:3000/api/heartbeat

If Umami loops during startup, read docker compose logs umami before changing the database. Common causes are a damaged DATABASE_URL, a missing .env, or PostgreSQL that never reached healthy state.

Change the default password through an SSH tunnel

Do not enable the public Caddy route yet. On first initialization, Umami creates the documented account admin with password umami. Publishing that login page before changing the password creates an avoidable takeover window.

From your workstation, forward the loopback-only listener and leave the tunnel running:

ssh -N -L 3000:127.0.0.1:3000 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:3000, sign in as admin with password umami, and replace it with a strong, unique password. Sign out, confirm the old password no longer works, then sign in with the new one. Close the tunnel only after that check passes.

Serve the dashboard and tracker over HTTPS

An HTTPS website will refuse to load an HTTP analytics script as mixed content. Put the dashboard, tracker, and collection endpoint behind the same valid TLS hostname.

With Caddy, add this block to /etc/caddy/Caddyfile:

analytics.example.com {
    reverse_proxy 127.0.0.1:3000
}

Caddy handles certificate issuance and forwards the original host, client address, and scheme. Validate, reload, and check the public heartbeat:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsS https://analytics.example.com/api/heartbeat

For Nginx, terminate TLS on 443, redirect port 80, and proxy to http://127.0.0.1:3000. Preserve Host, append X-Forwarded-For, and set X-Forwarded-Proto to the original scheme. Umami does not need an invented BASE_URL variable for this deployment; the proxy’s host and forwarded headers describe the public request. The Umami installation guide links to Nginx’s reverse-proxy documentation for this pattern.

Do not put blanket authentication in front of the whole hostname. The tracker script and /api/send collection endpoint must remain reachable from tracked websites. If you add another access layer for the dashboard, test its path rules carefully.

Record a real pageview

Browse to https://analytics.example.com and sign in with the password set through the SSH tunnel.

Add a website in the dashboard. Use the actual site hostname and a recognizable name, then open its tracking-code section. Umami generates the website ID and the exact snippet. It has this form:

<script
  defer
  src="https://analytics.example.com/script.js"
  data-website-id="WEBSITE-ID-FROM-UMAMI"
></script>

Copy the generated snippet into the tracked site’s <head>. Deploy that page and open it in a normal browser with tracker blocking disabled.

Use the browser’s Network panel to verify two requests: https://analytics.example.com/script.js loads successfully, and the collection request to /api/send returns a successful status. The Umami collection guide says the visit should appear immediately. Confirm the pageview in the dashboard’s realtime view, then repeat from another browser or device. This is the end-to-end test; a green container health check alone proves nothing about tracker delivery.

If the pageview does not appear, check the generated website ID, browser blockers, Content Security Policy, mixed-content errors, reverse-proxy logs, and Umami logs:

docker compose logs --tail=100 umami
curl -fsSI https://analytics.example.com/script.js

Back up PostgreSQL and configuration

Umami’s documentation has no application-specific backup procedure, so use PostgreSQL’s own tools. Use pg_dump rather than copying a live database volume; the custom format supports a controlled pg_restore:

cd /opt/umami
umask 077
install -d -m 0700 backups
docker compose exec -T db \
  pg_dump -U umami -d umami -Fc \
  > "backups/umami-$(date +%F).dump"
test -s "backups/umami-$(date +%F).dump"
chmod 600 "backups/umami-$(date +%F).dump"

Because compose.yaml pins exact image tags, the Compose file itself records which Umami and PostgreSQL versions produced the dump. Keep a copy of it with every dump and a restore can always use matching versions.

Preserve compose.yaml, the mode-600 .env, the reverse-proxy configuration, and any optional tracker endpoint settings in an encrypted, access-controlled backup. The dump contains analytics, users, teams, shares, and website definitions. The stable APP_SECRET and database password are configuration secrets, so do not store them in a public repository or beside an unencrypted public dump.

For the Caddy deployment in this guide, make a restricted configuration archive without displaying either secret:

sudo tar -czf "backups/umami-config-$(date +%F).tar.gz" \
  compose.yaml .env /etc/caddy/Caddyfile
sudo chmod 600 "backups/umami-config-$(date +%F).tar.gz"

Use the corresponding Nginx site file if you chose Nginx. Encrypt the configuration archive before copying it off the VPS.

Riven Cloud plans include daily provider backups as an extra safety net, but nothing replaces an application-consistent PostgreSQL dump that you have rehearsed restoring. Copy encrypted backups off the VPS. Database growth follows event volume and retention, so keep an eye on the volume and decide how long raw analytics should stay available.

Restore and prove the backup works

This restore drill uses a separate directory, Compose project, PostgreSQL volume, and loopback port. It never stops or drops the production database. Copy the production secrets and one dump into the isolated project without printing either one:

sudo install -d -m 0700 -o "$USER" -g "$USER" \
  /opt/umami-restore/backups
sudo install -m 0600 -o "$USER" -g "$USER" \
  /opt/umami/.env /opt/umami-restore/.env
sudo install -m 0600 -o "$USER" -g "$USER" \
  /path/to/umami-YYYY-MM-DD.dump \
  /opt/umami-restore/backups/umami-YYYY-MM-DD.dump
cd /opt/umami-restore

Create /opt/umami-restore/compose.yaml with the same pinned images as the production Compose file, a distinct database volume, and non-conflicting loopback port 3300:

services:
  umami:
    image: ghcr.io/umami-software/umami:3.2.0
    ports:
      - "127.0.0.1:3300:3000"
    environment:
      DATABASE_URL: "postgresql://umami:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/umami"
      APP_SECRET: "${APP_SECRET:?set APP_SECRET}"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test:
        ["CMD-SHELL", "curl -fsS http://localhost:3000/api/heartbeat || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 6
      start_period: 30s
    init: true
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}"
      TZ: UTC
      PGTZ: UTC
    volumes:
      - umami-restore-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 6
    restart: unless-stopped

volumes:
  umami-restore-db-data:

Start the isolated database. The new PostgreSQL volume contains a fresh, empty umami database, so no dropdb command is needed. Restore the dump, start the isolated application, and check its heartbeat:

cd /opt/umami-restore
test -s backups/umami-YYYY-MM-DD.dump
docker compose -p umami-restore up -d --wait --wait-timeout 120 db
docker compose -p umami-restore exec -T db pg_restore \
  -U umami -d umami \
  < backups/umami-YYYY-MM-DD.dump
docker compose -p umami-restore up -d --wait --wait-timeout 180 umami
curl -fsS http://127.0.0.1:3300/api/heartbeat

Inspect the restored dashboard without creating a public proxy route. From your workstation, open a second tunnel:

ssh -N -L 3300:127.0.0.1:3300 YOUR_USER@SERVER_IP

Browse to http://127.0.0.1:3300, log in with the restored account, and confirm the websites and historical reports exist. Keep production running while you compare a few known totals. Once a dump has passed this drill, you can rely on it.

Upgrade Umami safely

Umami updates can include database migrations. Read the release notes and official update guidance, and take a fresh logical dump first. The image tag is pinned, so pulling alone changes nothing; edit compose.yaml, set the Umami image tag to the release you reviewed, then pull and recreate:

docker compose pull umami
docker compose up -d --wait --wait-timeout 180
curl -fsS https://analytics.example.com/api/heartbeat

Wait for startup and migration logs to settle. On major upgrades or large migrated databases, Umami recommends refreshing PostgreSQL planner statistics:

docker compose exec -T db \
  psql -U umami -d umami -c 'ANALYZE;'

Log in, inspect an existing dashboard, load the tracker, and confirm a fresh pageview reaches /api/send and appears in realtime. Never use docker compose down -v; that removes the PostgreSQL volume.

Update the PostgreSQL 15 image separately

Keep database-image maintenance separate from an Umami application update, and take a fresh logical dump first. For a patch update within PostgreSQL major version 15:

cd /opt/umami
docker compose pull db
docker compose stop umami
docker compose up -d --wait --wait-timeout 120 db
docker compose up -d --wait --wait-timeout 180 umami
curl -fsS https://analytics.example.com/api/heartbeat

Log in and confirm an existing dashboard plus a new pageview. Keep the pre-update dump until those checks pass. A PostgreSQL major-version change is a database migration, not an image patch; follow PostgreSQL’s major-upgrade or logical dump/restore procedure instead of using the sequence above.

Choosing a Riven Cloud VPS for Umami

For most sites, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB transfer) is a comfortable starting point for Umami. Capacity follows event volume, retention, and report queries more than the number of tracked domains, so if the database grows or reports slow down, Ultra (8 GB RAM, 80 GB NVMe, 2 TB transfer) and Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) give you room to move up. A periodic look at PostgreSQL size, ingestion rate, and backup time will tell you when it is time.

One placement tip: put the collector near the visitors and the sites that send events. Latency for whoever opens the dashboard matters far less than latency on the tracking path. We offer Tokyo and Singapore on every plan, and if a meaningful share of your traffic comes from mainland China, comparing the Tokyo Looking Glass and Singapore Looking Glass from the relevant carriers at representative times is the quickest way to decide. The pricing page has the current plan details.

Security, privacy, and when not to self-host

Keep PostgreSQL private, retain the same APP_SECRET, patch both images, restrict backup access, and disable dashboard share URLs unless they are intentional. The collection endpoint is public by design. Anyone who obtains a website ID can submit fake events, so watch for report poisoning and disk growth. Apply proxy rate limits cautiously because a blunt limit can discard legitimate traffic bursts.

Analytics may involve consent, retention, deletion, data-location, or employee-monitoring obligations. IP-derived location and session identifiers may be personal data under applicable law. Review the current v3 session replay and heatmap features before enabling them because replay can capture sensitive page content or interactions. Umami sends anonymous product telemetry by default; the documented DISABLE_TELEMETRY=1 option disables it if your policy requires that.

Umami Cloud or another hosted analytics service is the better choice when nobody can own PostgreSQL backups, restores, migrations, monitoring, and privacy requests, or when you need vendor support, high availability, or a formal SLA. If basic request counts from web-server logs answer the question, a simpler single-binary log analyzer avoids a database, a tracker endpoint, and application migrations. Self-hosted Umami fits when its dashboard and event model are worth that ongoing operational work to you.

Version 2.20.15 was the current stable release when this article was checked on July 15, 2026. It fixes GHSA-8c6x-pfjq-9gr7, a low-severity flaw that let non-superusers delete superusers (releases before 2.20.14 are affected, 2.20.15 has the fix), and upstream recommends that all users upgrade. Read the 2.20.15 release notes and take a tested backup before upgrading.

A self-hosted Paperless-ngx server is an unmanaged deployment, so you run the operating system, TLS, access control, updates, monitoring, and recovery yourself and keep full control of the stack. Worth knowing up front: Paperless does not encrypt documents, extracted text, or filenames at rest. HTTPS protects traffic in transit; storage and backup encryption are separate decisions.

Prepare the VPS, DNS, and firewall

You need a VPS with root or sudo access, an A record for paperless.example.com, and off-server backup storage. Add an AAAA record only if IPv6 works through the host firewall and Caddy. Allow TCP 80 and 443 for HTTPS, plus the port used by administrative SSH. PostgreSQL, Redis, and Paperless port 8000 must never be public.

Install Docker Engine and the Compose plugin with Docker’s convenience script (or your distribution’s packages, if you’d rather not run a downloaded script as root):

curl -fsSL https://get.docker.com | sudo bash
sudo docker compose version

The remaining commands assume your account can run Docker. Otherwise, prefix each Docker command with sudo or follow Docker’s documented post-install procedure.

Install Caddy, UFW, and OpenSSL. Caddy also provides official package instructions if your distribution needs its repository.

sudo apt update
sudo apt install -y caddy ufw openssl
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

Replace 22 before enabling UFW if SSH uses another port (our SSH hardening guide explains how to move it safely), and mirror the rules in the provider firewall. Docker can bypass some host firewall paths when a port is published, which is another reason to keep the application binding explicitly on 127.0.0.1.

Generate secrets without printing them

Create the project and its two host directories. Paperless watches consume for incoming files and writes application exports under export.

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/paperless
sudo install -d -m 0750 -o "$USER" -g "$USER" \
  /opt/paperless/consume /opt/paperless/export
cd /opt/paperless

Generate a 256-bit Paperless secret and a 192-bit PostgreSQL password without displaying either value:

umask 077
{
  printf 'PAPERLESS_SECRET_KEY=%s\n' "$(openssl rand -hex 32)"
  printf 'PAPERLESS_DB_PASSWORD=%s\n' "$(openssl rand -hex 24)"
  printf 'USERMAP_UID=%s\n' "$(id -u)"
  printf 'USERMAP_GID=%s\n' "$(id -g)"
} > .env
chmod 600 .env

Keep .env unchanged across restarts and restores, and keep it out of tickets, terminal recordings, and Git. Paperless supports Docker secret files through _FILE variables if your secret-management system provides them; a mode-0600 file keeps this tutorial portable.

Create the Paperless Compose project

Create /opt/paperless/compose.yaml with the following content. It is a hardened single-VPS version of Paperless-ngx’s official PostgreSQL Compose file. The service roles and mount points follow upstream; the random database password, loopback port, webhook restrictions, health dependencies, and log limits are tutorial choices.

services:
  broker:
    image: redis:8
    restart: unless-stopped
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  db:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: paperless
      POSTGRES_USER: paperless
      POSTGRES_PASSWORD: "${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD}"
    volumes:
      - pgdata:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U paperless -d paperless"]
      interval: 10s
      timeout: 5s
      retries: 5
    logging:
      options:
        max-size: "10m"
        max-file: "3"

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:2.20.15
    restart: unless-stopped
    depends_on:
      broker:
        condition: service_healthy
      db:
        condition: service_healthy
    ports:
      - "127.0.0.1:${PAPERLESS_HOST_PORT:-8000}:8000"
    volumes:
      - data:/usr/src/paperless/data
      - media:/usr/src/paperless/media
      - ./export:/usr/src/paperless/export
      - ./consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBNAME: paperless
      PAPERLESS_DBUSER: paperless
      PAPERLESS_DBPASS: "${PAPERLESS_DB_PASSWORD:?set PAPERLESS_DB_PASSWORD}"
      PAPERLESS_URL: "${PAPERLESS_EXTERNAL_URL:-https://paperless.example.com}"
      PAPERLESS_ALLOWED_HOSTS: "${PAPERLESS_ALLOWED_HOSTS:-paperless.example.com}"
      PAPERLESS_SECRET_KEY: "${PAPERLESS_SECRET_KEY:?set PAPERLESS_SECRET_KEY}"
      PAPERLESS_TIME_ZONE: UTC
      PAPERLESS_OCR_LANGUAGE: eng
      PAPERLESS_TASK_WORKERS: "1"
      PAPERLESS_THREADS_PER_WORKER: "1"
      PAPERLESS_PROXY_SSL_HEADER: '["HTTP_X_FORWARDED_PROTO", "https"]'
      PAPERLESS_WEBHOOKS_ALLOWED_PORTS: "80,443"
      PAPERLESS_WEBHOOKS_ALLOW_INTERNAL_REQUESTS: "false"
      USERMAP_UID: "${USERMAP_UID:?set USERMAP_UID}"
      USERMAP_GID: "${USERMAP_GID:?set USERMAP_GID}"
    logging:
      options:
        max-size: "10m"
        max-file: "3"

volumes:
  data:
  media:
  pgdata:
  redisdata:

Replace every paperless.example.com before starting. PAPERLESS_URL must have no trailing slash or path. The explicit allowed host removes the insecure public default of *. Caddy overwrites X-Forwarded-Proto, and only the loopback proxy can reach port 8000, so trusting that header is appropriate for this layout. PostgreSQL and Redis use the major-version tags from the upstream 2.20.15 template, so they pick up patch releases automatically.

Start the private stack and check the listener:

cd /opt/paperless
docker compose up -d --wait --wait-timeout 180
curl -fsSL http://127.0.0.1:8000/ > /dev/null
sudo ss -lntp | grep ':8000'

The listener must show 127.0.0.1:8000, not 0.0.0.0:8000.

Create the superuser before public access

Paperless can create an administrator from environment variables, but that leaves a plaintext password in long-lived configuration. Use the interactive management command from the official setup documentation instead:

cd /opt/paperless
docker compose exec webserver createsuperuser

Choose a non-obvious username, a real administrative email address, and a unique password from a password manager. The command hashes the password in the database and does not add it to .env or shell history. Do not add the public Caddy route until this command succeeds.

Put Caddy in front of Paperless

Paperless requires a TLS reverse proxy for Internet exposure. Its interface uses WebSocket connections, and uploads can exceed the small request-body defaults in some proxy examples. Caddy handles WebSocket upgrades and the standard forwarded headers automatically. Keep this site in a separate imported file so adding Paperless does not erase existing hosts. This block adds an explicit 100 MB proxy-side upload ceiling:

sudo install -d -m 755 /etc/caddy/sites-enabled
sudo tee /etc/caddy/sites-enabled/paperless.caddy > /dev/null <<'CADDY'
paperless.example.com {
    request_body {
        max_size 100MB
    }
    reverse_proxy 127.0.0.1:8000
}
CADDY

if ! sudo grep -Eq \
  '^[[:space:]]*import[[:space:]]+/etc/caddy/sites-enabled/\*' \
  /etc/caddy/Caddyfile; then
  printf '\nimport /etc/caddy/sites-enabled/*\n' | \
    sudo tee -a /etc/caddy/Caddyfile > /dev/null
fi

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -fsSI https://paperless.example.com/

Change the ceiling to match the largest document you intend to accept. A 413 Request Entity Too Large points to the proxy or an application upload limit, while a stalled interface can mean broken WebSocket forwarding. Nginx users must explicitly configure HTTP/1.1 upgrade headers and raise client_max_body_size; a bare proxy_pass is incomplete.

Sign in over HTTPS with the CLI-created account. Enable multi-factor authentication if your identity setup supports it, and do not create broad user accounts merely to feed the consume directory.

Verify a real upload and OCR result

A green health check only proves that the web process answers HTTP. Test the workflow with a harmless image-only scan that contains a unique phrase, such as paperless ocr test 20260714. A phone photograph saved as JPEG works, and it forces Paperless to run OCR rather than read an existing PDF text layer.

Upload the image from the web interface. Watch Tasks until consumption finishes, then open the document and confirm all of the following:

1. The original image opens and downloads.
2. The document page contains extracted text with the unique phrase.
3. Searching for that phrase returns the document.
4. The archived representation and thumbnail render correctly.

If processing fails, read the consumer and OCR output before raising resource limits:

cd /opt/paperless
docker compose logs --tail=250 webserver

OCR is CPU and memory intensive. Multiple languages increase processing time, and untrusted PDFs or oversized images can exhaust resources or hit bugs in parsers such as Ghostscript and ImageMagick. Keep PAPERLESS_TASK_WORKERS * PAPERLESS_THREADS_PER_WORKER at or below the VPS’s logical CPU count. The conservative one-by-one setting above is intentional. Do not disable image-pixel safeguards or allow anonymous uploads.

Back up with document_exporter

Provider snapshots help with whole-host recovery, but a snapshot taken while PostgreSQL and Paperless are writing may not be application consistent. Paperless’s backup documentation provides document_exporter to export documents, thumbnails, settings, and database content. API tokens are not included and must be recreated after recovery.

Pause watched mailboxes, scanners, and uploads, then wait for the Tasks view to become idle. Run the official exporter through Compose and checksum the result:

cd /opt/paperless
backup="backup-$(date +%F-%H%M%S)"
docker compose exec -T webserver \
  document_exporter "../export/$backup" --no-progress-bar
find "export/$backup" -type f -print0 \
  | sort -z \
  | xargs -0 -r sha256sum > "export/$backup.sha256"

Record the Paperless version (2.20.15) alongside the export; the importer requires an exact version match. Copy the export, checksum, compose.yaml, Caddy configuration, and encrypted secret material off the VPS. The export contains the documents you were trying to protect, so encrypt it and restrict access at the destination. A copy on the same disk is not a backup.

Rehearse an isolated same-version restore

Paperless requires document_importer to run against an empty installation of exactly the same version. The drill below builds that empty installation beside production, in its own Compose project on an alternate loopback port. A separate test VPS is safer, since a same-host drill shares the Docker daemon, RAM, disk, and port space with production; if you use one, copy the Compose file, .env, and the latest export there first and adjust the source paths.

For a same-host drill, keep all commands in one shell:

set -Eeuo pipefail
restore_project="paperless-restore-$(date +%Y%m%d%H%M%S)"
restore_dir="/opt/$restore_project"
backup_dir=$(find /opt/paperless/export -mindepth 1 -maxdepth 1 \
  -type d -name 'backup-*' | sort | tail -n 1)
backup_name=$(basename "$backup_dir")
sudo install -d -m 0700 -o "$USER" -g "$USER" \
  "$restore_dir/consume" "$restore_dir/export"
sudo install -m 0600 -o "$USER" -g "$USER" \
  /opt/paperless/.env "$restore_dir/.env"
sudo install -m 0640 -o "$USER" -g "$USER" \
  /opt/paperless/compose.yaml "$restore_dir/compose.yaml"
sudo cp -a "$backup_dir" "$restore_dir/export/"
sudo chown -R "$USER":"$USER" "$restore_dir"
cd "$restore_dir"
export PAPERLESS_HOST_PORT=18000
export PAPERLESS_EXTERNAL_URL=http://127.0.0.1:18000
export PAPERLESS_ALLOWED_HOSTS=127.0.0.1,localhost

docker compose -p "$restore_project" up -d --wait --wait-timeout 180
docker compose -p "$restore_project" exec webserver \
  document_importer "../export/$backup_name"
docker compose -p "$restore_project" exec webserver document_sanity_checker
curl -fsSL http://127.0.0.1:18000/ > /dev/null

The timestamped project name gives the drill its own containers, volumes, and network, so document_importer runs against a fresh, empty database. The importer still requires the export and target to use exactly the same Paperless version; an empty newer installation is not compatible.

Tunnel port 18000 over SSH, log in with a restored account, and inspect several originals, archived files, thumbnails, metadata, permissions, and searches. Recreate an API token if an integration needs one. The sanity checker catches internal inconsistencies, but it cannot prove that every document is readable or that an external integration still works.

After the rehearsal, remove the restore project and its isolated volumes:

cd "$restore_dir"
docker compose -p "$restore_project" down -v

Never run the importer over the production installation, and never use down -v in /opt/paperless; there it deletes the production volumes.

Upgrade and roll back deliberately

Before an upgrade, stop new ingestion, wait for active tasks, run document_sanity_checker, create a fresh exporter backup, and read every release note between the installed and target versions. Then update the version tag in compose.yaml.

Paperless’s official Docker procedure stops the stack, pulls, and starts it in the foreground so database migrations remain visible:

cd /opt/paperless
docker compose exec webserver document_sanity_checker
docker compose down
docker compose pull
docker compose up

Watch for migration or worker errors. In another SSH session, test login, search, and a fresh OCR upload. Then stop the foreground run with Ctrl+C and return it to detached mode:

cd /opt/paperless
docker compose up -d --wait --wait-timeout 180
docker compose exec webserver document_sanity_checker

Do not roll back by pointing an older image at a database migrated by a newer release. A safe rollback uses the pre-upgrade export with the old, exact Paperless version in a new empty deployment. Rehearse it on an alternate port, then switch Caddy only after documents, search, permissions, and OCR pass. PostgreSQL major upgrades need PostgreSQL’s own migration or a logical dump and restore; do not bundle them into a routine Paperless update.

Keep Tika and Gotenberg optional

The baseline handles the normal PDF and image workflow without Tika or Gotenberg. Enable the pair only if you need Office documents or email formats that require conversion. Paperless’s official Tika Compose template adds apache/tika and Gotenberg, then sets PAPERLESS_TIKA_ENABLED=1 and internal endpoints for both services.

That template uses gotenberg/gotenberg:8.25 and apache/tika:latest. The latter is a mutable tag; pin a specific version if you want repeatable deployments. Do not publish ports 3000 or 9998. Preserve the upstream Gotenberg arguments --chromium-disable-javascript=true and --chromium-allow-list=file:///tmp/.*; they reduce remote-content and JavaScript exposure while converting email. Tika and Gotenberg parse more untrusted formats and use more CPU and RAM, so they expand both the attack surface and the sizing requirement.

Choosing a Riven Cloud VPS for Paperless-ngx

For a personal document archive with the conservative one-worker OCR settings above, our Premium plan (2 vCPU, 4 GB RAM, 40 GB NVMe, 1 TB monthly transfer) is a comfortable starting point. Move up to Ultra (2 vCPU, 8 GB RAM, 80 GB NVMe, 2 TB transfer) if you want faster OCR on a large backlog or plan to enable Tika and Gotenberg, and to Max (4 vCPU, 16 GB RAM, 160 GB NVMe, 4 TB transfer) when the originals, archived files, thumbnails, and PostgreSQL start crowding the disk. Storage tends to grow long after the initial import, while an OCR backlog only needs CPU for a while, so watching disk usage usually tells you first when it is time to resize. If the archive will share its VPS with other services, our roundup of self-hosted apps is a good place to gauge what co-hosts comfortably alongside an OCR workload.

All three plans include a 1 Gbps port, full root access, daily backups, and a choice of Tokyo or Singapore. The daily backups are a good safety net for whole-host recovery; keep the application-consistent exporter backups and the restore drill above in place as well. If you or your users connect from mainland China, take a moment to test the Tokyo Looking Glass and Singapore Looking Glass from your own network before choosing a location, then compare the current Riven Cloud VPS plans.

Security and privacy limits

Paperless removed its old built-in document encryption. Original and archived files are readable by the application, extracted document text is stored in plaintext in PostgreSQL, and filenames are not encrypted. Use an encrypted filesystem or encrypted block volume if you need protection from physical-media access, and always encrypt off-server exports. Access controls, TLS, and disk encryption solve different problems.

Workflow webhooks also deserve attention. Upstream defaults allow HTTP and HTTPS on any port and permit internal requests. The environment values above restrict ports to 80 and 443 and disable internal webhook requests, which reduces server-side request forgery risk. Treat those settings as one layer; container egress rules should also block cloud metadata and management networks, especially when less-trusted users can create workflows.

Do not accept uploads from anonymous or untrusted users. OCR and document parsers handle complex, attacker-controlled files and have no blanket sandbox guarantee from Paperless. Keep Paperless, the host, and every parser image patched; retain image-pixel limits; cap proxy upload size; and monitor CPU, memory, disk, and task queues.

Self-hosting Paperless-ngx works well when someone owns those controls, application-aware backups, restore tests, and security updates. If the archive needs built-in per-document encryption, contractual high availability, or formal records controls, a managed document system is the better home for it; a single unmanaged VPS is not designed to provide those guarantees.

This guide deploys linkding 1.45.0 from the official Docker Hub image on Debian or Ubuntu. Port 9090 stays bound to loopback, the first superuser is created before Caddy exposes the service, and host firewall rules block the container from private, link-local, and metadata address ranges.

Set up this way, linkding makes a pleasant private bookmark service for trusted users. The two habits worth keeping are treating the outbound fetcher as attack surface and testing your restores instead of assuming the copies work.

Prerequisites

Prepare:

• a Debian or Ubuntu VPS with root or sudo access;
• an A record for bookmarks.example.com pointing to the VPS, plus an AAAA record only when the complete IPv6 path is configured;
• TCP 80 and 443 for Caddy and your existing administrative SSH port;
• a trusted administrator account and no plan to offer open registration;
• encrypted off-server backup storage;
• an unused private Docker subnet. This guide uses 172.31.50.0/24.

Check that the example subnet does not overlap an existing host or container route:

ip route
sudo docker network ls