Learning Restic - Repository Initialization

#Introduction

In episode 2 you understood the three-pillar architecture: repository, snapshot, and chunking. Now it is time to build the first pillar — a real repository. Initialization is a step you only do once, but mistakes here (especially around the password) become long-term disasters.

Keep this principle in mind: restic init creates the repository structure and an encryption key protected by a password. After this, the password is everything.

#Preparing Environment Variables

Before every restic command, get into the habit of exporting two variables so you do not have to repeat the flags:

export RESTIC_REPOSITORY=/backup/restic
export RESTIC_PASSWORD='h4sH-yang-sangat-Panjang-dan-Unik'

RESTIC_REPOSITORY replaces -r, and RESTIC_PASSWORD avoids the interactive prompt — a must when used in cron or systemd (episode 9).

#Initializing a Local Repository

Initializing the local backend takes a single command:

restic init --repo /backup/restic

Successful output

created restic repository 2223e26e6b at /backup/restic
 
Please note that knowledge of your password is required to access
the repository. Losing your password means that your data is
irrecoverably lost.

Without RESTIC_PASSWORD, restic will ask for the password twice. The note in the output is not empty words — losing the password means permanent data loss, and even restic itself has no backdoor.

#Initializing an S3 Repository

For an S3-compatible backend (MinIO, AWS S3, GCS, Azure), the target is a bucket URL:

export AWS_ACCESS_KEY_ID=minioadmin
export AWS_SECRET_ACCESS_KEY=minioadmin
restic init -r s3:https://minio.example.com/backup-bucket

The bucket must already exist; restic does not create it automatically. For public S3 such as AWS, use the regional endpoint:

restic init -r s3:s3.ap-southeast-1.amazonaws.com/backup-bucket

The differences between backends and their configuration examples are covered in full in episode 7.

#Using --repository-file

Instead of writing the URL in every command or env, store it in a file (for example /etc/restic/repo):

restic --repository-file /etc/restic/repo init

The file content is just one line: the repository URL. This makes centralized configuration and sharing the repository across scripts easier.

#Managing the Password Securely

The repository password is the key to all your data. Here are some storage patterns, from the simplest to enterprise-grade:

#1. Environment Variable

export RESTIC_PASSWORD="$(cat /etc/restic/passphrase)"

#2. GPG-encrypted file

gpg -c /etc/restic/passphrase
export RESTIC_PASSWORD_FILE=/etc/restic/passphrase.gpg

RESTIC_PASSWORD_FILE makes restic decrypt the file containing the password with gpg on every use.

#3. Secret Manager

For production, store it in Vault/OpenBao, AWS Secrets Manager, or a password manager, then inject it as an environment variable when the backup process runs.

#Common Mistakes During Init

• Init in a non-empty directory: restic refuses with repository master key and config already initialized or a similar error. Always use a dedicated empty directory/bucket for the repository.
• Password misconfigured: the prompt appears even though RESTIC_PASSWORD is set — usually because the variable was not exported or the name is misspelled.
• S3 bucket does not exist: init fails with repository master key and config already initialized only on a retry; the initial error is usually AccessDenied or NoSuchBucket — create the bucket first.
• Forgotten password: there is no recovery. Keep a backup copy of the password in a location separate from the repository.

#Conclusion

• restic init creates the repository + a password-protected encryption key.
• Use RESTIC_REPOSITORY and RESTIC_PASSWORD to avoid repeated prompts.
• S3 backend: restic -r s3:... init, make sure the bucket is created first.
• --repository-file separates the repo configuration from the command.
• Store the password in env, gpg, or a secret manager — not in git.
• Forgotten password = permanent data loss. There are no shortcuts.

In the next episode, episode 4, we run the first backup & snapshot — backing up a directory with tags and excludes, then inspecting the results with restic snapshots, restic stats, and restic ls. Your repository will come to life.