pawelorzech/autoscript
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

readme updates

Browse source
This commit is contained in:
Paweł Orzech 2025-08-03 13:34:27 +02:00
parent 4736972c4e
commit e63470e51d
2 changed files with 308 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
README.md
View file

@ -5,6 +5,9 @@
<a href="#7-licencja">
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
</a>
<a href="README_en.md">
<img src="https://img.shields.io/badge/lang-EN-blue.svg" alt="English">
</a>
</p>
<h1 align="center">AutoScript: Zintegrowana Platforma Serwerowa</h1>

305
README_en.md Normal file
View file

@ -0,0 +1,305 @@
<p align="center">
<a href="#">
<img src="https://img.shields.io/badge/AutoScript-v5.0-blue.svg" alt="AutoScript Version">
</a>
<a href="#7-license">
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
</a>
<a href="README.md">
<img src="https://img.shields.io/badge/lang-PL-red.svg" alt="Polish">
</a>
</p>
<h1 align="center">AutoScript: Integrated Server Platform</h1>
**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](#1-platform-architecture-overview)
2. [Configuration Guide: Key Acquisition](#2-configuration-guide-key-acquisition)
3. [Installation (Quick Start)](#3-installation-quick-start)
4. [Command Guide](#4-command-guide)
5. [Backup and Restore](#5-backup-and-restore)
6. [Security Aspects](#6-security-aspects)
7. [License](#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:
```bash
ssh-keygen -t ed25519 -C "your-email@example.com"
```
2. Copy the content of the public key:
```bash
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](https://dash.cloudflare.com/)
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](https://www.backblaze.com/) 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:
```bash
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**.
```bash
# 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.
```bash
# 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.
```bash
# 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.
```bash
# 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:
```bash
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:
```bash
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:
```bash
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.
```bash
# 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.
```bash
# 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.