abra-debian-scripts

Helper scripts for installing Abra on Debian. While it probably works on any Debian system, it is geared towards beginners and is friendly for anyone on Windows machines as it has been tested on the Windows Sub-system for Linux 2 (WSL2).

🛠️ Abra Setup Scripts

This repository contains a set of scripts designed to help you configure and deploy applications using the Abra command line (CLI) tool on your computer to manage remote servers.

📖 Table of Contents

Introduction Repository Structure Key concepts Prerequisites Getting Started Script Overview Troubleshooting Additional Resources

📝 Introduction

This repository includes a set of Bash scripts that handle the creation and configuration of SSH keys, server connections, and Abra settings, making it easier for new users to get up and running quickly.

The scripts are primarily designed to work with Git, Docker, and Abra, and they have been tested on Debian-based systems. They can also be used on WSL2 setups for Windows users, providing a smooth integration between Windows and Linux environments.

📁 Repository Structure

Here's a quick overview of the main files in this repository:

• config.sh.example:
  Contains the server, Git, and path configurations used by the setup script. This is where you can customize the shared settings use by yourself and potentially your team so that the configuration only needs to be set once.

• setup_abra.sh:
  The main setup script that will configure SSH keys, connect to your Git and Abra servers, and set up Abra CLI.

💡 Key concepts

In case you are new to the Abra world, here are some key concepts:

• Abra: The tool used to manage remote servers to host apps online - such as wordpress or other web tools and systems.
• Debian: A linux operating system distribution that Abra can use
• SSH: Secure shell for securely connecting to remote servers. This protocol is used widely for communication on the internet and Abra uses it too.
• SSH keys: The equivalent of a password or secret to be able to uniquely identify yourself and gain access to a server. These scripts will generate SSH keys for you. Protect these.
• Public key: The SSH key that is publicly shared and used by others, especially remote computers, to know that you are the one communicating with them
• Private key: The SSH key that you must be keep to yourself and never shared with anyone, not even an administrator. This is used to identify yourself uniquely. The fact that you have this key can be verified with the public key on the server and is how the server knows who you are and can communicate securely.
• Git: A tool used keep track of files (a version control system). Abra works out of a git "repository", like this one, to store settings for server apps and to access recipes for how to run apps on the server.
• Docker: A tool to create an app-specific environment that allows apps to be isolated from one another and from the server. These container-based environments add a layer of additional security and often simplify the management and development of apps.

📋 Prerequisites

Before you get started, ensure you have the following:

1. A remote server where you can connect via SSH with a a friendly server admin who can add your public SSH key. Never share a private key.
2. Access to a Git server (e.g., Gitea) where the Abra repository is stored and where you will add your own public SSH key.
3. A Linux-based OS (Debian or Ubuntu) or WSL2 on Windows with an Debian or Ubuntu container.

🚀 Getting Started

Step 1: Configuring the scripts

You may skip this step and go to step 2 if the scripts have been configured for you.

Follow these steps to set up your environment and start using the Abra setup scripts:

1. Clone this repository to your local machine:

On Windows, make sure you install Git for Windows first. On Linux or WSL2, you will need to ensure git is already installed.

git clone https://git.washnote.org/nickdickinson/abra-debian-scripts
cd abra-debian-scripts

Copy the file config.sh.example to config.sh and then open it in your favorite text editor.

If on Windows, make sure you use one like VSCode or Notepad++ that will not add windows line-endings.

2. Edit the configuration file (config.sh):

Open the config.sh file in a text editor and update the values to match your settings:

# Git Configuration
GIT_REPO_URL="git@git.example.org:WASHNote/example-apps.git"
GIT_SSH_HOST="git.example.org"
GIT_SSH_PORT="22"
GIT_USER="git"

# Abra Server Configuration (shared)
ABRA_SERVER_HOST="example.org"
ABRA_SERVER_PORT="22"

# Path configuration - this is the default - do not change unless required
ABRA_PATH="~/.local/bin"

# SSH Key Configuration
SSH_KEY_FILE="$HOME/.ssh/id_ed25519"

Save the file after editing.

Step 2: Run the setup script

1. Copy scripts to your home and make them executable

On Windows, from a normal windows shell:

wsl cp config.sh ~/config.sh
wsl cp setup_bash.sh ~/setup_bash.sh
wsl chmod +x ~/setup_bash.sh

On Linux or from a WSL2 shell:

cp config.sh ~/config.sh
cp setup_bash.sh ~/setup_bash.sh
cd ~
chmod +x ./setup_bash.sh

2. Run your scripts

On Windows, you will now need to open your Ubuntu or Debian shell. Abra will be installed and live in Linux.

Use the following command to run the setup script from your home director. Make sure to replace and with your own email address and username from the server you are managing with Abra:

cd ~ # go to your home directory
./setup_abra.sh <your-email> <abra-server-user>

For example:

./setup_abra.sh myemail@example.com myusername

Note: At the moment, the script may need to be re-run after the installation of Abra. If it stops because Abra was not added to the path, simply follow the instructions and after that run it again.

3. Follow the on-screen instructions:

• The script will guide you through adding your SSH keys to both the Git and Abra app servers.
• You will need to confirm when you have added the keys before continuing.

When the script completes, if it succeeds, it will list the status of all applications manage by Abra on your server.

📚 Additional Resources

For more information on how to use the Abra CLI, refer to the official documentation:

• Abra documentation

If you are new to Docker or SSH, start with

• SSH Debian documentation
• Docker intro

Authorship and AI disclosure

These scripts and the readme were created by Nicolas Dickinson based on existing documentation, experimentation in WSL2 Debian and partly generated and debugged during testing by Nicolas Dickinson using OpenAI ChatGPT in September 2024.