PostgreSQL backup tool with Point-In-Time-Recovery and restore verification
TypeScript backupbackupsdatabasedatabase-backupdevopsdockergolangkubernetesmariadbmongodbmysqlpgpostgrespostgresqls3self-hostedsystem-administrationtoolsweb-ui
FEATURE (agent): Make installation guide more structured
Rostislav Duginaa01ce0b7650
diff --git a/frontend/src/features/databases/ui/AgentInstallationComponent.tsx b/frontend/src/features/databases/ui/AgentInstallationComponent.tsxindex 242a6c95..9f4803f6 100644--- a/frontend/src/features/databases/ui/AgentInstallationComponent.tsx+++ b/frontend/src/features/databases/ui/AgentInstallationComponent.tsx@@ -72,71 +72,281 @@ export const AgentInstallationComponent = ({ database, onTokenGenerated }: Props);const downloadCommand = `curl -L -o databasus-agent "${databasusHost}/api/v1/system/agent?arch=${selectedArch}" && chmod +x databasus-agent`;+ const pgHbaEntry = `host replication all 127.0.0.1/32 md5`;+ const grantReplicationSql = `ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;`;- const walQueuePath = pgDeploymentType === 'docker' ? '/wal-queue' : '/opt/databasus/wal-queue';+ // -- Step 2: Configure postgresql.conf --- const postgresqlConfSettings = `wal_level = replica+ const renderStep2System = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 2 — Configure postgresql.conf</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Add or update these settings in your <code>postgresql.conf</code>.+ </p>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Typical location — Debian/Ubuntu:{' '}+ <code>/etc/postgresql/<version>/main/postgresql.conf</code>, RHEL/CentOS:{' '}+ <code>/var/lib/pgsql/<version>/data/postgresql.conf</code>+ </p>+ {renderCodeBlock(`wal_level = replicaarchive_mode = on-archive_command = 'cp %p ${walQueuePath}/%f.tmp && mv ${walQueuePath}/%f.tmp ${walQueuePath}/%f'`;+archive_command = 'cp %p /opt/databasus/wal-queue/%f.tmp && mv /opt/databasus/wal-queue/%f.tmp /opt/databasus/wal-queue/%f'`)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Restart PostgreSQL to apply the changes:+ </p>+ {renderCodeBlock('sudo systemctl restart postgresql')}+ </div>+ );- const pgHbaEntry = `host replication all 127.0.0.1/32 md5`;+ const renderStep2Folder = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 2 — Configure postgresql.conf</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Add or update these settings in the <code>postgresql.conf</code> inside your PostgreSQL data+ directory.+ </p>+ {renderCodeBlock(`wal_level = replica+archive_mode = on+archive_command = 'cp %p /opt/databasus/wal-queue/%f.tmp && mv /opt/databasus/wal-queue/%f.tmp /opt/databasus/wal-queue/%f'`)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Restart PostgreSQL to apply the changes:+ </p>+ {renderCodeBlock('pg_ctl -D <YOUR_PG_DATA_DIR> restart')}+ </div>+ );- const grantReplicationSql = `ALTER ROLE <YOUR_PG_USER> WITH REPLICATION;`;+ const renderStep2Docker = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 2 — Configure postgresql.conf</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Add or update these settings in your <code>postgresql.conf</code> inside the container. The{' '}+ <code>/wal-queue</code> path in <code>archive_command</code> is the path{' '}+ <strong>inside the container</strong> — it must match the volume mount target configured in+ Step 5.+ </p>+ {renderCodeBlock(`wal_level = replica+archive_mode = on+archive_command = 'cp %p /wal-queue/%f.tmp && mv /wal-queue/%f.tmp /wal-queue/%f'`)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Restart the container to apply the changes:+ </p>+ {renderCodeBlock('docker restart <CONTAINER_NAME>')}+ </div>+ );- const createWalDirCommand = `mkdir -p /opt/databasus/wal-queue`;+ // -- Step 3: Configure pg_hba.conf --- const walDirPermissionsCommand = `chown postgres:postgres /opt/databasus/wal-queue-chmod 755 /opt/databasus/wal-queue`;+ const renderStep3System = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 3 — Configure pg_hba.conf</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Add this line to <code>pg_hba.conf</code> to allow <code>pg_basebackup</code> to take full+ backups via a local replication connection. Adjust the address and auth method as needed.+ </p>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Typical location — Debian/Ubuntu:{' '}+ <code>/etc/postgresql/<version>/main/pg_hba.conf</code>, RHEL/CentOS:{' '}+ <code>/var/lib/pgsql/<version>/data/pg_hba.conf</code>+ </p>+ {renderCodeBlock(pgHbaEntry)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Restart PostgreSQL to apply the changes:+ </p>+ {renderCodeBlock('sudo systemctl restart postgresql')}+ </div>+ );- const dockerWalDirPermissionsCommand = `# Inside the container (or via docker exec):-chown postgres:postgres /wal-queue`;+ const renderStep3Folder = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 3 — Configure pg_hba.conf</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Add this line to <code>pg_hba.conf</code> in your PostgreSQL data directory to allow{' '}+ <code>pg_basebackup</code> to take full backups via a local replication connection. Adjust+ the address and auth method as needed.+ </p>+ {renderCodeBlock(pgHbaEntry)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Restart PostgreSQL to apply the changes:+ </p>+ {renderCodeBlock('pg_ctl -D <YOUR_PG_DATA_DIR> restart')}+ </div>+ );++ const renderStep3Docker = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 3 — Configure pg_hba.conf</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Add this line to <code>pg_hba.conf</code> inside the container to allow{' '}+ <code>pg_basebackup</code> to take full backups via a replication connection on the+ container's loopback interface. Adjust the address and auth method as needed.+ </p>+ {renderCodeBlock(pgHbaEntry)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Restart the container to apply the changes:+ </p>+ {renderCodeBlock('docker restart <CONTAINER_NAME>')}+ </div>+ );++ // -- Step 5: WAL queue directory --++ const renderStep5System = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 5 — Create WAL queue directory</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ PostgreSQL will place WAL archive files here for the agent to upload.+ </p>+ {renderCodeBlock('mkdir -p /opt/databasus/wal-queue')}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Ensure the directory is writable by PostgreSQL and readable by the agent:+ </p>+ {renderCodeBlock(`chown postgres:postgres /opt/databasus/wal-queue+chmod 755 /opt/databasus/wal-queue`)}+ </div>+ );++ const renderStep5Folder = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 5 — Create WAL queue directory</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ PostgreSQL will place WAL archive files here for the agent to upload.+ </p>+ {renderCodeBlock('mkdir -p /opt/databasus/wal-queue')}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Ensure the directory is writable by PostgreSQL and readable by the agent:+ </p>+ {renderCodeBlock(`chown postgres:postgres /opt/databasus/wal-queue+chmod 755 /opt/databasus/wal-queue`)}+ </div>+ );- const dockerVolumeExample = `# In your docker run command:+ const renderStep5Docker = () => (+ <div>+ <div className="font-semibold dark:text-white">Step 5 — Set up WAL queue volume</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ The WAL queue directory must be a <strong>volume mount</strong> shared between the+ PostgreSQL container and the host. The agent reads WAL files from the host path, while+ PostgreSQL writes to the container path via <code>archive_command</code>.+ </p>+ {renderCodeBlock('mkdir -p /opt/databasus/wal-queue')}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Then mount it as a volume so both the container and the agent can access it:+ </p>+ {renderCodeBlock(`# In your docker run command:docker run ... -v /opt/databasus/wal-queue:/wal-queue ...# Or in docker-compose.yml:volumes:- - /opt/databasus/wal-queue:/wal-queue`;-- const buildStartCommand = () => {- const baseFlags = [- ` --databasus-host=${databasusHost}`,- ` --db-id=${database.id}`,- ` --token=<YOUR_AGENT_TOKEN>`,- ` --pg-host=localhost`,- ` --pg-port=5432`,- ` --pg-user=<YOUR_PG_USER>`,- ` --pg-password=<YOUR_PG_PASSWORD>`,- ];-- const baseFlagsWithContinuation = baseFlags.map((f) => f + ' \\');-- if (pgDeploymentType === 'system') {- return [- './databasus-agent start \\',- ...baseFlagsWithContinuation,- ` --pg-type=host \\`,- ` --pg-wal-dir=/opt/databasus/wal-queue`,- ].join('\n');- }+ - /opt/databasus/wal-queue:/wal-queue`)}+ <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">+ Ensure the directory inside the container is owned by the <code>postgres</code> user:+ </p>+ {renderCodeBlock(`# Inside the container (or via docker exec):+chown postgres:postgres /wal-queue`)}+ </div>+ );- if (pgDeploymentType === 'folder') {- return [- './databasus-agent start \\',- ...baseFlagsWithContinuation,- ` --pg-type=host \\`,- ` --pg-host-bin-dir=<PATH_TO_PG_BIN_DIR> \\`,- ` --pg-wal-dir=/opt/databasus/wal-queue`,- ].join('\n');- }+ // -- Step 6: Start the agent --++ const buildBaseFlags = () => [+ ` --databasus-host=${databasusHost} \\`,+ ` --db-id=${database.id} \\`,+ ` --token=<YOUR_AGENT_TOKEN> \\`,+ ` --pg-host=localhost \\`,+ ` --pg-port=5432 \\`,+ ` --pg-user=<YOUR_PG_USER> \\`,+ ` --pg-password=<YOUR_PG_PASSWORD> \\`,+ ];++ const renderStep6System = () => {+ const startCommand = [+ './databasus-agent start \\',+ ...buildBaseFlags(),+ ` --pg-type=host \\`,+ ` --pg-wal-dir=/opt/databasus/wal-queue`,+ ].join('\n');++ return (+ <div>+ <div className="font-semibold dark:text-white">Step 6 — Start the agent</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Replace placeholders in <code>{'<ANGLE_BRACKETS>'}</code> with your actual values.+ </p>+ {renderCodeBlock(startCommand)}+ </div>+ );+ };++ const renderStep6Folder = () => {+ const startCommand = [+ './databasus-agent start \\',+ ...buildBaseFlags(),+ ` --pg-type=host \\`,+ ` --pg-host-bin-dir=<PATH_TO_PG_BIN_DIR> \\`,+ ` --pg-wal-dir=/opt/databasus/wal-queue`,+ ].join('\n');++ return (+ <div>+ <div className="font-semibold dark:text-white">Step 6 — Start the agent</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Replace placeholders in <code>{'<ANGLE_BRACKETS>'}</code> with your actual values.{' '}+ <code>--pg-host-bin-dir</code> should point to the directory containing{' '}+ <code>pg_basebackup</code> (e.g. <code>/usr/lib/postgresql/17/bin</code>).+ </p>+ {renderCodeBlock(startCommand)}+ </div>+ );+ };- return [+ const renderStep6Docker = () => {+ const startCommand = ['./databasus-agent start \\',- ...baseFlagsWithContinuation,+ ...buildBaseFlags(),` --pg-type=docker \\`,` --pg-docker-container-name=<CONTAINER_NAME> \\`,` --pg-wal-dir=/opt/databasus/wal-queue`,].join('\n');++ return (+ <div>+ <div className="font-semibold dark:text-white">Step 6 — Start the agent</div>+ <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">+ Replace placeholders in <code>{'<ANGLE_BRACKETS>'}</code> with your actual values.+ </p>+ <p className="mt-1 text-sm text-amber-600 dark:text-amber-400">+ Use the PostgreSQL port <strong>inside the container</strong> (usually 5432), not the+ host-mapped port.+ </p>+ {renderCodeBlock(startCommand)}+ </div>+ );+ };++ // -- Dispatch helpers --++ const renderStep2 = () => {+ if (pgDeploymentType === 'system') return renderStep2System();+ if (pgDeploymentType === 'folder') return renderStep2Folder();+ return renderStep2Docker();+ };++ const renderStep3 = () => {+ if (pgDeploymentType === 'system') return renderStep3System();+ if (pgDeploymentType === 'folder') return renderStep3Folder();+ return renderStep3Docker();+ };++ const renderStep5 = () => {+ if (pgDeploymentType === 'system') return renderStep5System();+ if (pgDeploymentType === 'folder') return renderStep5Folder();+ return renderStep5Docker();+ };++ const renderStep6 = () => {+ if (pgDeploymentType === 'system') return renderStep6System();+ if (pgDeploymentType === 'folder') return renderStep6Folder();+ return renderStep6Docker();};return (@@ -247,31 +457,8 @@ volumes:{renderCodeBlock(downloadCommand)}</div>- <div>- <div className="font-semibold dark:text-white">Step 2 — Configure postgresql.conf</div>- <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">- Add or update these settings in your <code>postgresql.conf</code>, then{' '}- <strong>restart PostgreSQL</strong>.- </p>- {pgDeploymentType === 'docker' && (- <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">- The <code>archive_command</code> path (<code>/wal-queue</code>) is the path{' '}- <strong>inside the container</strong>. It must match the volume mount target — see- Step 5.- </p>- )}- {renderCodeBlock(postgresqlConfSettings)}- </div>-- <div>- <div className="font-semibold dark:text-white">Step 3 — Configure pg_hba.conf</div>- <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">- Add this line to <code>pg_hba.conf</code>. This is required for{' '}- <code>pg_basebackup</code> to take full backups — not for streaming replication. Adjust- the address and auth method as needed, then reload PostgreSQL.- </p>- {renderCodeBlock(pgHbaEntry)}- </div>+ {renderStep2()}+ {renderStep3()}<div><div className="font-semibold dark:text-white">Step 4 — Grant replication privilege</div>@@ -282,58 +469,8 @@ volumes:{renderCodeBlock(grantReplicationSql)}</div>- <div>- <div className="font-semibold dark:text-white">- Step 5 —{' '}- {pgDeploymentType === 'docker'- ? 'Set up WAL queue volume'- : 'Create WAL queue directory'}- </div>- {pgDeploymentType === 'docker' ? (- <>- <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">- The WAL queue directory must be a <strong>volume mount</strong> shared between the- PostgreSQL container and the host. The agent reads WAL files from the host path,- while PostgreSQL writes to the container path via <code>archive_command</code>.- </p>- {renderCodeBlock(createWalDirCommand)}- <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">- Then mount it as a volume so both the container and the agent can access it:- </p>- {renderCodeBlock(dockerVolumeExample)}- <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">- Ensure the directory inside the container is owned by the <code>postgres</code>{' '}- user:- </p>- {renderCodeBlock(dockerWalDirPermissionsCommand)}- </>- ) : (- <>- <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">- PostgreSQL will place WAL archive files here for the agent to upload.- </p>- {renderCodeBlock(createWalDirCommand)}- <p className="mt-2 text-sm text-gray-600 dark:text-gray-400">- Ensure the directory is writable by PostgreSQL and readable by the agent:- </p>- {renderCodeBlock(walDirPermissionsCommand)}- </>- )}- </div>-- <div>- <div className="font-semibold dark:text-white">Step 6 — Start the agent</div>- <p className="mt-1 text-sm text-gray-600 dark:text-gray-400">- Replace placeholders in <code>{'<ANGLE_BRACKETS>'}</code> with your actual values.- </p>- {pgDeploymentType === 'docker' && (- <p className="mt-1 text-sm text-amber-600 dark:text-amber-400">- Use the PostgreSQL port <strong>inside the container</strong> (usually 5432), not the- host-mapped port.- </p>- )}- {renderCodeBlock(buildStartCommand())}- </div>+ {renderStep5()}+ {renderStep6()}<div><div className="font-semibold dark:text-white">After installation</div>