Skip to content

Commit e35a648

Browse files
RostislavDuginRostislavDugin
committed
FEATURE (docs): Add FAQ section and update logo
1 parent 39eaf81 commit e35a648

File tree

9 files changed

+311
-58
lines changed

9 files changed

+311
-58
lines changed

‎app/components/DocTableOfContentComponent.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,8 @@ export default function DocTableOfContentComponent() {
6060
const element = document.getElementById(id);
6161
if (element) {
6262
element.scrollIntoView({ behavior: "smooth", block: "start" });
63+
// Update URL hash without triggering a scroll
64+
window.history.pushState(null, "", `#${id}`);
6365
}
6466
};
6567

‎app/components/DocsSidebarComponent.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,10 @@ const navItems: NavItem[] = [
3939
title: "Reset password",
4040
href: "/password",
4141
},
42+
{
43+
title: "FAQ",
44+
href: "/faq",
45+
},
4246
{
4347
title: "Contribute",
4448
href: "/contribute",

‎app/faq/page.tsx‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
import type { Metadata } from "next";
2+
import DocsNavbarComponent from "../components/DocsNavbarComponent";
3+
import DocsSidebarComponent from "../components/DocsSidebarComponent";
4+
import DocTableOfContentComponent from "../components/DocTableOfContentComponent";
5+
import { CopyButton } from "../components/CopyButton";
6+
7+
export const metadata: Metadata = {
8+
title: "FAQ - Frequently Asked Questions | Postgresus",
9+
description:
10+
"Frequently asked questions about Postgresus PostgreSQL backup tool. Learn how to backup localhost databases, understand backup formats, compression methods and more.",
11+
keywords: [
12+
"Postgresus FAQ",
13+
"PostgreSQL backup questions",
14+
"localhost database backup",
15+
"backup formats",
16+
"pg_dump compression",
17+
"zstd compression",
18+
"PostgreSQL backup help",
19+
"database backup guide",
20+
],
21+
openGraph: {
22+
title: "FAQ - Frequently Asked Questions | Postgresus",
23+
description:
24+
"Frequently asked questions about Postgresus PostgreSQL backup tool. Learn how to backup localhost databases, understand backup formats, compression methods and more.",
25+
type: "article",
26+
url: "https://postgresus.com/faq",
27+
},
28+
twitter: {
29+
card: "summary",
30+
title: "FAQ - Frequently Asked Questions | Postgresus",
31+
description:
32+
"Frequently asked questions about Postgresus PostgreSQL backup tool. Learn how to backup localhost databases, understand backup formats, compression methods and more.",
33+
},
34+
alternates: {
35+
canonical: "https://postgresus.com/faq",
36+
},
37+
robots: "index, follow",
38+
};
39+
40+
export default function FAQPage() {
41+
const dockerComposeHost = `services:
42+
postgresus:
43+
container_name: postgresus
44+
image: rostislavdugin/postgresus:latest
45+
network_mode: host
46+
volumes:
47+
- ./postgresus-data:/postgresus-data
48+
restart: unless-stopped`;
49+
50+
const dockerRunHost = `docker run -d \\
51+
--name postgresus \\
52+
--network host \\
53+
-v ./postgresus-data:/postgresus-data \\
54+
--restart unless-stopped \\
55+
rostislavdugin/postgresus:latest`;
56+
57+
return (
58+
<>
59+
{/* JSON-LD Structured Data */}
60+
<script
61+
type="application/ld+json"
62+
dangerouslySetInnerHTML={{
63+
__html: JSON.stringify({
64+
"@context": "https://schema.org",
65+
"@type": "FAQPage",
66+
mainEntity: [
67+
{
68+
"@type": "Question",
69+
name: "How to backup localhost databases?",
70+
acceptedAnswer: {
71+
"@type": "Answer",
72+
text: "To backup databases running on localhost, you need to configure Postgresus to use host network mode in Docker. This allows the container to access services running on your host machine (localhost).",
73+
},
74+
},
75+
{
76+
"@type": "Question",
77+
name: "Why does Postgresus not use raw SQL dump format?",
78+
acceptedAnswer: {
79+
"@type": "Answer",
80+
text: "Postgresus uses the directory format with zstd compression because it provides the most efficient backup and restore speed after extensive testing. The directory format with zstd compression level 5 offers the optimal balance between backup creation speed, restore speed, and file size.",
81+
},
82+
},
83+
],
84+
}),
85+
}}
86+
/>
87+
88+
<DocsNavbarComponent />
89+
90+
<div className="flex min-h-screen">
91+
{/* Sidebar */}
92+
<DocsSidebarComponent />
93+
94+
{/* Main Content */}
95+
<main className="flex-1 px-4 py-6 sm:px-6 sm:py-8 lg:px-12">
96+
<div className="mx-auto max-w-4xl">
97+
<article className="prose prose-blue max-w-none">
98+
<h1 id="faq">Frequently Asked Questions</h1>
99+
100+
<p className="text-lg text-gray-700">
101+
Find answers to the most common questions about Postgresus,
102+
including installation, configuration, and backup strategies.
103+
</p>
104+
105+
<h2 id="how-to-backup-localhost">
106+
How to backup localhost databases?
107+
</h2>
108+
109+
<p>
110+
If you&apos;re running Postgresus in Docker and want to back up
111+
databases running on your host machine (localhost), you need to
112+
configure Docker to use <strong>host network mode</strong>.
113+
</p>
114+
115+
<p>
116+
By default, Docker containers run in an isolated network and
117+
cannot access services on <code>localhost</code>. The host
118+
network mode allows the container to share the host&apos;s
119+
network namespace.
120+
</p>
121+
122+
<h3 id="docker-compose-solution">Solution for Docker Compose:</h3>
123+
124+
<p>
125+
Update your <code>docker-compose.yml</code> file to use{" "}
126+
<code>network_mode: host</code>:
127+
</p>
128+
129+
<div className="relative my-6">
130+
<pre className="overflow-x-auto rounded-lg bg-gray-900 p-4 text-sm text-gray-100">
131+
<code>{dockerComposeHost}</code>
132+
</pre>
133+
<div className="absolute right-2 top-2">
134+
<CopyButton text={dockerComposeHost} />
135+
</div>
136+
</div>
137+
138+
<h3 id="docker-run-solution">Solution for Docker run:</h3>
139+
140+
<p>
141+
Use the <code>--network host</code> flag:
142+
</p>
143+
144+
<div className="relative my-6">
145+
<pre className="overflow-x-auto rounded-lg bg-gray-900 p-4 text-sm text-gray-100">
146+
<code>{dockerRunHost}</code>
147+
</pre>
148+
<div className="absolute right-2 top-2">
149+
<CopyButton text={dockerRunHost} />
150+
</div>
151+
</div>
152+
153+
<div className="rounded-lg border border-blue-200 bg-blue-50 p-4 my-6 pb-0">
154+
<p className="text-sm text-blue-900 m-0">
155+
<strong>💡 Note:</strong> When using host network mode, you
156+
can connect to your localhost database using{" "}
157+
<code>127.0.0.1</code> or <code>localhost</code> as the host
158+
in your Postgresus backup configuration. You&apos;ll also
159+
access the Postgresus UI directly at{" "}
160+
<code>http://localhost:4005</code> without port mapping.
161+
</p>
162+
</div>
163+
164+
<div className="rounded-lg border border-amber-200 bg-amber-50 p-4 my-6 pb-0">
165+
<p className="text-sm text-amber-900 m-0">
166+
<strong>⚠️ Important for Windows and macOS users:</strong> The{" "}
167+
<code>host</code> network mode only works natively on Linux.
168+
On Windows and macOS, Docker runs inside a Linux VM, so{" "}
169+
<code>host.docker.internal</code> should be used instead of{" "}
170+
<code>localhost</code> as the database host address in your
171+
backup configuration.
172+
</p>
173+
</div>
174+
175+
<h2 id="why-no-raw-sql-dump">
176+
Why does Postgresus not use raw SQL dump format?
177+
</h2>
178+
179+
<p>
180+
Postgresus uses the <code>pg_dump</code>&apos;s{" "}
181+
<strong>directory format</strong> with{" "}
182+
<strong>zstd compression at level 5</strong> instead of the
183+
plain SQL format because it provides the most efficient balance
184+
between:
185+
</p>
186+
187+
<ul>
188+
<li>Backup creation speed</li>
189+
<li>Restore speed</li>
190+
<li>
191+
File size compression (up to 20x times smaller than plain SQL
192+
format)
193+
</li>
194+
</ul>
195+
196+
<p>
197+
This decision was made after extensive testing and benchmarking
198+
of different PostgreSQL backup formats and compression methods.
199+
You can read more about testing here{" "}
200+
<a
201+
href="https://dev.to/rostislav_dugin/postgresql-backups-comparing-pgdump-speed-in-different-formats-and-with-different-compression-4pmd"
202+
target="_blank"
203+
rel="noopener noreferrer"
204+
>
205+
PostgreSQL backups: comparing pg_dump speed in different
206+
formats and with different compression
207+
</a>
208+
.
209+
</p>
210+
211+
<p>Postgresus will not include raw SQL dump format, because:</p>
212+
213+
<ul>
214+
<li>extra variety is bad for UX;</li>
215+
<li>makes it harder to support the code;</li>
216+
<li>current dump format is suitable for 99% of the cases</li>
217+
</ul>
218+
219+
<p>
220+
As for Nov 2025 Postgresus is going to add incremental backups
221+
support. So this is priority in addition to current dump format.
222+
</p>
223+
</article>
224+
</div>
225+
</main>
226+
227+
{/* Table of Contents */}
228+
<DocTableOfContentComponent />
229+
</div>
230+
</>
231+
);
232+
}

‎app/favicon.ico‎

0 Bytes
Binary file not shown.

‎app/sitemap.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,12 @@ export default function sitemap(): MetadataRoute.Sitemap {
3131
changeFrequency: "monthly",
3232
priority: 0.8,
3333
},
34+
{
35+
url: `${baseUrl}/faq`,
36+
lastModified: currentDate,
37+
changeFrequency: "monthly",
38+
priority: 0.9,
39+
},
3440
{
3541
url: `${baseUrl}/storages`,
3642
lastModified: currentDate,

0 commit comments

Comments
 (0)