pawelorzech/autoscript
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
autoscript/README_en.md
Paweł Orzech e63470e51d readme updates
2025-08-03 13:34:27 +02:00

16 KiB
Raw Permalink Blame History

AutoScript Version License Polish

AutoScript: Integrated Server Platform

AutoScript is a fully integrated, automated, and secure solution for deploying and managing a complete, multi-service server platform. This project transforms a "bare" server into a ready-to-use, secure, and monitored environment, capable of hosting a wide range of applications simultaneously.

Table of Contents

  1. Platform Architecture: Service Overview
  2. Configuration Guide: Key Acquisition
  3. Installation (Quick Start)
  4. Command Guide
  5. Backup and Restore
  6. Security Aspects
  7. License

1. Platform Architecture: Service Overview

AutoScript builds a comprehensive ecosystem of services, ready to use right after installation:

Category Service Role in System
Social Networks Mastodon Decentralized, federated social network.
Discussion Forums Discourse Modern, full-featured forum platform.
Blog System WordPress The world's most popular content management system (CMS), ideal for running a blog or site.
RSS Reader FreshRSS Personal news aggregator and RSS feed reader, hosted on your server.
Email Server Self-hosted mail server Complete, self-sufficient mail server (IMAP/SMTP) with an admin panel.
Mail Synchronization imapsync Tool for bulk email account migration and synchronization between servers.
Monitoring and Status Uptime Kuma Dashboard for monitoring the availability of all your services with a public status page.
Infrastructure Traefik, Docker, PostgreSQL, etc. Robust foundation consisting of reverse proxy, containerization, and databases.

2. Configuration Guide: Key Acquisition

SSH Key

  1. Generate SSH key pair on your local computer: 
    ssh-keygen -t ed25519 -C "your-email@example.com"
  2. Copy the content of the public key: 
    cat ~/.ssh/id_ed25519.pub
  3. Use this content as the PUBLIC_KEY value in the configuration file.

Cloudflare API Token

  1. Log in to Cloudflare Dashboard
  2. Go to My Profile > API Tokens
  3. Click Create Token and select the Custom token template
  4. Set permissions:
    • Zone: Zone:Read
    • Zone: DNS:Edit
  5. Select the appropriate DNS zone
  6. Copy the generated token as CF_DNS_API_TOKEN

Backup Keys (Backblaze B2)

  1. Log in to your Backblaze account.
  2. Go to "B2 Cloud Storage" > "Buckets" and create a new private bucket.
  3. Go to "App Keys" and generate a new application key with access to your bucket. You will need applicationKeyId (as B2_ACCOUNT_ID) and applicationKey (as B2_ACCOUNT_KEY).

3. Installation: From Zero to a Working Platform

This section is a detailed, complete guide that will take you from zero to a fully operational, secure platform. Execute commands in the given order. We assume you start with a freshly installed server with Debian 12 or Ubuntu 22.04+.

Step 1: Initial Server Connection

Immediately after creating a server with your hosting provider, you will receive an IP address. Connect to the server as the root user using an SSH terminal. On your local computer (Linux, macOS, Windows with WSL or Git Bash), enter:

ssh root@<YOUR_SERVER_IP>

You will be asked for the root password provided by your hosting provider.

Step 2: Download AutoScript

Once logged in as root on the server, your first task is to install git (if it's not there) and download the AutoScript code. Execute all the following commands on the server.

# Update the list of available packages and install git
apt update && apt install -y git

# Clone the repository into /root/autoscript folder and navigate into it
git clone https://github.com/pawelorzech/autoscript.git && cd autoscript

Step 3: Platform Configuration

This is the crucial step where you define how your platform will operate. You need to create a configuration file and fill it with your data.

# Create a copy of the example file
cp autoscript.conf.example autoscript.conf

# Open the configuration file in a simple text editor
nano autoscript.conf

The nano editor will open. Use the arrows to navigate the file. Carefully fill in all required variables, following the instructions from the "Configuration Guide: Key Acquisition" section. Pay special attention to PUBLIC_KEY, CF_DNS_API_TOKEN, and domains for individual services.

To save the file and exit the nano editor:

  1. Press Ctrl + X.
  2. Press Y (to confirm save).
  3. Press Enter (to confirm the filename).

Step 4: Configuration Validation

Before making any changes in the system, run a validation. The script will check if the API keys are correct and if it can connect to the required services. This is your safety net.

# Make sure you are in the /root/autoscript folder
sudo ./start.sh validate

If the validation is successful, you are ready to install. If not, the script will inform you what needs to be corrected in the autoscript.conf file.

Step 5: Installation Initiation

Execute the main installation command. The script will do the rest. Sit back; the process can take several minutes.

# Make sure you are in the /root/autoscript folder
sudo ./start.sh install

The script will install all packages, configure security, deploy all services in Docker containers, and link them into a seamlessly functioning ecosystem.

Step 6: Post-Installation Steps (Very Important!)

Once the script finishes its work, your server is ready, but its security has been fundamentally changed:

  1. Logging in as root is BLOCKED.
  2. SSH Port is CHANGED to a random number within the range 10000-65535. To find out, execute on the server: 
    cat /root/ssh_port.txt
  3. A new admin user has been created. From now on, you log in only to this account using your SSH key and the new port. On your local computer, execute: 
    ssh admin@<YOUR_SERVER_IP> -p <NEW_PORT_FROM_FILE>
  4. 2FA Configuration (TOTP): The first time you use sudo (e.g., sudo ls /root), a QR code will appear on the screen. Scan it with a Google Authenticator or Authy type app and save backup codes in a safe place! They are one-time use and necessary to recover access if the phone is lost.

Your platform is now ready to use. Services will be available under the domains configured in the autoscript.conf file.

4. Command Guide

AutoScript is controlled with simple, logical commands. All commands must be run from the /root/autoscript folder with sudo privileges.

Main Commands

  • sudo ./start.sh install Meta-command used once at the start. Initiates in the proper order all necessary installation modules: validation, system hardening, deploying Traefik, monitoring, and all configured services. Ideal for quick start.

  • sudo ./start.sh uninstall VERY DANGEROUS! This command completely removes everything created by AutoScript: containers, application data, Docker volumes, and even uninstalls packages. Use only when you want to entirely clear the server. The script will prompt for confirmation to prevent accidental use.

  • sudo ./start.sh validate Your safety net. Checks the correctness of the autoscript.conf file, verifies API keys and tokens but makes no system changes. Always run this command after configuration changes.

Service Management Commands

You can manage each service independently. This is useful for redeploying or updating specific components.

  • sudo ./start.sh deploy_mastodon
  • sudo ./start.sh deploy_discourse
  • sudo ./start.sh deploy_wordpress
  • sudo ./start.sh deploy_freshrss
  • sudo ./start.sh deploy_mail
  • sudo ./start.sh deploy_status
  • sudo ./start.sh deploy_monitoring
  • sudo ./start.sh deploy_traefik

Backup Management Commands

  • sudo ./start.sh backup:init Initializes a new, empty backup repository in your Backblaze B2 bucket. You must do this once before automatic backup works.

  • sudo ./start.sh backup:run Manually starts the process of creating a new, encrypted backup of the entire /opt/services folder.

  • sudo ./start.sh backup:list Displays a list of all available snapshots in your backup repository.

  • sudo ./start.sh backup:restore <SNAPSHOT_ID> Restores the selected snapshot to the /opt/services.restored folder. Does not overwrite existing data, giving you full control over the recovery process.

Utility Commands

  • sudo ./start.sh secrets:edit <service_name> Safely opens an encrypted secret file for a given service (e.g., mastodon) in the default editor. After saving, the file is automatically re-encrypted.

  • sudo ./start.sh secrets:view <service_name> Securely displays the decrypted contents of the secret file on screen without saving it anywhere in plain text.

  • sudo ./start.sh self-update Updates the AutoScript to the latest version from the Git repository. It's recommended to run regularly.

5. Backup and Restore

AutoScript is fully integrated with Restic and Backblaze B2 to ensure the safety of your data.

  • Automation: After proper configuration, the script automatically creates a cron job that daily performs an encrypted backup of the entire /opt/services folder (containing all application data) to your B2 bucket.
  • Recovery: In the event of a failure, you can use the command sudo ./start.sh backup:restore <SNAPSHOT_ID> to recover data.

6. Security Aspects: "Secure by Default" Architecture

AutoScript does not take security as an option but as a fundamental element built into every aspect of the platform. Here are the key defense mechanisms that are automatically deployed:

Operating System Level

  • Minimization of Attack Surface: The script installs only necessary packages. There is no redundant software that could pose a potential threat.
  • Strengthened Authentication: Password login to SSH is completely disabled. Access is only possible using cryptographic keys. Additionally, access to root privileges (via sudo) is protected by two-factor authentication (TOTP).
  • Access Control: Logging into the root account is blocked. The dedicated admin user has limited privileges, which can only be elevated using sudo (with 2FA verification).
  • Firewall (UFW): The firewall is configured in "deny all, allow selected" mode. Only ports necessary for the operation of deployed services are opened.

Application and Network Level

  • Proactive Intrusion Protection (IPS): CrowdSec analyzes network behavior and proactively blocks IP addresses known for malicious activity globally. Fail2ban additionally monitors logs for brute-force attack attempts.
  • End-to-End Encryption: All traffic to your services is automatically encrypted with SSL/TLS certificates from Let's Encrypt, managed by Traefik.
  • Container Isolation: All services run in Docker containers, isolating them from each other and the host system. Additionally, enabling userns-remap maps the root user inside the container to a regular user on the host, drastically limiting potential damage in case of container "escape."

Data Level

  • Secret Management (sops): All sensitive data – API keys, database passwords, tokens – are encrypted on disk using sops and the age key. They are never stored in plain text.
  • Encrypted Backups: All backups created by Restic are encrypted end-to-end before being sent to an external location (Backblaze B2). Without the repository password, no one can read your data.

7. Post-Installation Steps: What Next?

Congratulations! Your platform is fully installed, secured, and ready to work. Here's what you should do now to fully take control of it and start using it.

1. First Login and Application Configuration

Each of the installed services is now available under the domain you configured in the autoscript.conf file. It's time to visit them and complete their configuration from the web interface.

  • Mastodon (https://your-domain.ovh): Go to the main page and register your first account. The first registered account automatically receives the instance owner role.
  • Discourse (https://forum.your-domain.ovh): Like Mastodon, register an admin account to start configuring forum categories and settings.
  • WordPress (https://blog.your-domain.ovh): Go through the famous "five-minute setup" of WordPress to set up the site title, create an admin account, and start writing.
  • FreshRSS (https://rss.your-domain.ovh): Log in and start adding your favorite RSS feeds.
  • Mail Server (https://your-domain.ovh/admin): Log in to the mail admin panel using the MAIL_ADMIN_PASSWORD from the configuration file. Here you can add domains and mailboxes.
  • Status Dashboard (https://status.your-domain.ovh): Configure Uptime Kuma by creating monitors for all your new services to track their availability.

2. Access to Data and Secrets

All your application data (databases, uploaded files) are located in the /opt/services/ folder. You can browse them as the admin user.

If you need to check the generated database password or another secret, use the built-in command:

sudo ./start.sh secrets:view <service_name>
# Example:
sudo ./start.sh secrets:view mastodon

3. Backup Management

Backups are configured, but it's worth checking their status. You can manually start a backup or list existing snapshots.

# Manually running a backup
sudo ./start.sh backup:run

# Displaying the list of all backups in the repository
sudo ./start.sh backup:list

4. System Monitoring

Explore the Grafana dashboard to see how your server is performing.

  • Grafana (https://grafana.your-domain.ovh): Log in using the GRAFANA_ADMIN_PASSWORD from the configuration file. There you'll find pre-configured dashboards showing CPU usage, memory, container status, and much more.
  • Alertmanager (https://alertmanager.your-domain.ovh): Here you can see active alerts. By default, they are sent to your ADMIN_EMAIL.

5. Updates

Remember to regularly update both the operating system and the AutoScript itself.

# Update system packages
sudo apt update && sudo apt upgrade -y

# Update AutoScript to the latest version
sudo ./start.sh self-update

Your platform is now fully in your hands. Experiment, create, and enjoy the freedom of having your own, powerful infrastructure!

8. License

The project is available under the MIT license.