---
title: "Backing up Harblet"
description: "Back up Harblet's own database and restore it onto a fresh server."
canonical_url: "https://harblet.com/docs/backups/harblet-backups"
---
# Backing up Harblet

> Back up Harblet's own database and restore it onto a fresh server.

Harblet's own database holds your accounts, projects, services and their settings, environment variables, domains, certificates and the list of backups. Harblet backs it up like any other database, and you can restore it onto a fresh server.

<note>

Settings → Backups is for admins.

</note>

## Set up the backup

<steps level="3">

### Choose a destination

Go to **Settings** → **Backups**. Choose a [backup destination](https://harblet.com/docs/backups/backup-destinations), a schedule and how many scheduled backups to keep, then click **Save**. Click **Back up now** to take the first backup right away.

### Keep the app secret

On the same page, the **App secret** card shows the secret of this install, hidden. Click the eye button to show it, or the copy button to copy it, and keep it somewhere safe, for example in your password manager.

</steps>

<caution>

**Without the app secret, a backup can't be fully restored.** Harblet encrypts environment variables, database passwords, the private keys of certificates and GitHub Apps, GitLab access tokens, and the access keys of destinations with it. The secret isn't in the backup. A backup restored without it can't read these values.

</caution>

Harblet's backups are stored at `<folder>/harblet-system/postgres/<time>.dump` in the bucket. You can download and delete them under **Settings** → **Backups**. They can't be restored from there, because Harblet restores itself while it's installed on a new server.

## Restore Harblet onto a new server

Restore Harblet when its first server is lost, or to move it to another server.

<steps level="3">

### Prepare a fresh server

Set up a server that meets the [requirements](https://harblet.com/docs/getting-started/installation#requirements).

### Copy the backup to the server

Take the newest file from the folder `harblet-system/postgres` at your destination, or download it under **Settings** → **Backups** while the old install still runs. Copy it to the new server as `backup.dump`.

### Run the install script with the backup

On the new server, in the folder that holds `backup.dump`, download the install script and run it with your app secret:

```bash [New server]
curl -fsSL https://raw.githubusercontent.com/harblet/harblet/main/install.sh -o install.sh
sudo HARBLET_APP_SECRET=your-app-secret HARBLET_BACKUP=backup.dump sh install.sh
```

The **Restore** card under **Settings** → **Backups** has the second command ready to copy.

If the server is behind NAT, add `HARBLET_URL` as for a [normal install](https://harblet.com/docs/getting-started/installation#servers-behind-nat).

When it's done, the script prints:

```text
Harblet is ready with the restored backup. Open http://203.0.113.20:3000 and log in.
```

### Log in

Open the address and log in with your existing account.

</steps>

## After the restore

The restore brings back Harblet's data, but nothing runs yet. Bring your services back in this order:

1. **Point your domains at the new server.** Change the DNS A records of Harblet's domain and of your services' domains to the new server's IP address.
2. **Give Harblet its domain again** under **Settings** → **General**. Harblet starts at `http://<ip>:3000` after a restore. See [Harblet's domain](https://harblet.com/docs/administration/harblet-domain).
3. **Deploy each database,** then restore its newest backup from its **Backups** tab. Databases start empty on the new server.
4. **Deploy your other services.** Git services build again.
5. **Add your other servers again,** if you had any. See [Servers](https://harblet.com/docs/administration/servers). Uninstall k3s on them first with `sudo /usr/local/bin/k3s-agent-uninstall.sh`.

<tip>

Practice a restore on a spare server once, so you know it works before you need it.

</tip>

## Errors

<table>
<thead>
  <tr>
    <th>
      Message
    </th>
    
    <th>
      What to do
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      backup.dump isn't a backup of Harblet's database. Set HARBLET_BACKUP to the .dump file from the backup destination.
    </td>
    
    <td>
      Check that <code>
        backup.dump
      </code>
      
       is in the current folder and was copied completely, and that it comes from the <code>
        harblet-system/postgres
      </code>
      
       folder.
    </td>
  </tr>
  
  <tr>
    <td>
      Restoring a backup needs the app secret of the install it comes from. Set HARBLET_APP_SECRET to it.
    </td>
    
    <td>
      Add <code>
        HARBLET_APP_SECRET
      </code>
      
       to the command.
    </td>
  </tr>
  
  <tr>
    <td>
      HARBLET_APP_SECRET isn't an app secret. An app secret has 64 characters, the digits 0 to 9 and the letters a to f.
    </td>
    
    <td>
      Copy the app secret again, without spaces or line breaks.
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://harblet.com/sitemap.md) for all pages.