Skip to content

Git repository

Tip

It's highly recommended you setup your repositories before installing the server. You can skip this for now, but doing so might lead to issues. Especially if you've not worked with Git or SSH before.

Requirements:

GitHub account

You'll need a GitHub account to store your Git repositories.

Alternatively, you can also use any other Git forge like Codeberg.org. Which is a non-profit, community-led effort that provides Git hosting.

Info

This guide assumes you're using GitHub.

SSH keys

Next you'll need an SSH key pair. If you're new to using SSH keys, I highly recommended doing some research on them first.

The easiest and much more secure way to store SSH keys is inside a password manager with SSH agent support (i.e 1Password, Bitwarden).

Info

Generating Ed25519 keys is preferred over RSA or ECDSA.

After creating your SSH key pair, you'll need to add them to your GitHub account. It's best to have at least two key pairs, one for authentication and ideally a second pair for signing.

Git repositories

You will need to create two new Git repos:

The former will be your version of the karo-stack tooling, it's a public repo. Whereas the latter is a much smaller private repo, which will only contain your personal configiuration. It will be placed inside the karo-stack as a subdirectory.

Tip

If you create your repositories on GitHub you can safely disable these unnecessary features:

  1. Edit repository details on the main page
  2. Disable Releases, Packages and Deployments
  3. Go to Settings > General > Features
  4. Disable Issues and Projects

Local setup

Using your system's terminal, run the following commands to clone your two repos locally:

Info

It's recommended to use Git BASH on Windows.

Question

This method uses SSH to connect to GitHub. It's important to use this method now as this is what the server will require later on.

# On the server, this should be done at `cd /srv`
git clone git@github.com:<username>/karo-stack.git karo

cd karo
git clone git@github.com:<username>/inventory.git inventory

Inventory files

Your inventory repo will eventually look something like this:

inventory/
├── hosts.ini
├── host_vars
│   └── homeserver
│       └── vault.yml
└── key.txt

For now, it's important to create the following two files...

inventory/hosts.ini

This config is used to tell the automation tool Ansible where to target. As we'll be running Ansible on the server itself, you can simply copy the following:

[server]
homeserver ansible_host=localhost ansible_connection=local ansible_user=karo

Development

For remote connections, use this setup instead

[server]
homeserver ansible_host=192.168.122.142 ansible_connection=ssh ansible_user=karo

inventory/key.txt

This file will store your public SSH authentication key. And should look similar to the following example:

ssh-ed25519 AAAAC3NzaNeXaMpLeTz5AAAAIGHz6gYzXhlvpyk7yizgqmz84XzmY+mIRXMgzkIXSRof

Commit changes

Once you've added your files to your inventory repo you'll need to commit and push your changes.

cd inventory

git add hosts.ini
git commit -m "add ansible hosts.ini config"

git add key.txt
git commit -m "add public ssh key file"

git push