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

readme + changelog updates

Browse source
This commit is contained in:
Paweł Orzech 2025-08-03 12:57:13 +02:00
parent 09b8886adb
commit 78d25de10c
2 changed files with 185 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
CHANGELOG.md
View file

@ -1,6 +1,18 @@
# Changelog
## 2025-08-03 (v3.0) - Architektura modularna
Ten plik dokumentuje wszystkie znaczące zmiany wprowadzone w projekcie AutoScript.
---
## v3.1 (2025-08-03) - Kompletna Dokumentacja
### Zmieniono
- **Kompletna przebudowa `README.md`**: Plik `README.md` został przepisany od podstaw, aby służyć jako jedyne, wyczerpujące źródło dokumentacji dla projektu. Dodano szczegółowe opisy filozofii projektu, architektury, przewodnika po konfiguracji, aspektów bezpieczeństwa i roadmapy.
---
## v3.0 (2025-08-03) - Architektura Modularna
### Dodano
@ -10,20 +22,73 @@
- **Zaawansowane Zarządzanie Sekretami (`secrets:edit`, `secrets:view`)**: Dodano komendy-pomocniki do łatwiejszego zarządzania sekretami za pomocą `sops`.
- **Aktualizacja Skryptu (`self-update`)**: Dodano komendę do automatycznej aktualizacji skryptu z repozytorium Git.
- **Ulepszone Logowanie**: Wprowadzono kolorowe logi na konsoli (INFO, WARN, ERROR) oraz ujednolicony zapis do pliku `/var/log/autoscript.log`.
- **Przygotowano fundamenty pod przyszłe funkcje**: Stworzono puste funkcje (stubs) dla:
- Wdrożenia Mastodona (`deploy_mastodon`).
- Dynamicznego odkrywania usług przez Prometheus.
- Centralnego logowania dla hosta z Promtail.
- Interaktywnej konfiguracji.
- Wzmocnienia bezpieczeństwa kontenerów (AppArmor).
- Zaawansowanych kopii zapasowych (`backup:run`, `backup:restore`).
- **Przygotowano fundamenty pod przyszłe funkcje**: Stworzono puste funkcje (stubs) dla kluczowych, planowanych modułów.
### Zmieniono
- **Kompletna przebudowa `start.sh`**: Skrypt został przepisany od podstaw, aby zaimplementować nową, modularną architekturę.
- **Rozbudowa `autoscript.conf.example`**: Dodano nowe zmienne konfiguracyjne na potrzeby przyszłych modułów.
- **Dokumentacja**: `README.md` zostało całkowicie przepisane, aby szczegółowo opisać nową architekturę, komendy i zaawansowane koncepcje.
---
(Poprzednie wersje poniżej)
## v2.3 (2025-08-03) - Zmiana Domeny Głównej
### Zmieniono
- **Domyślna Struktura Domen**: Zmieniono domyślną konfigurację projektu, aby używać `social.ovh` jako domeny głównej, a usługi pomocnicze (Grafana, Prometheus) umieścić na jej subdomenach.
- Zaktualizowano wszystkie odpowiednie szablony konfiguracyjne i dokumentację, aby odzwierciedlały tę zmianę.
---
## v2.2 (2025-08-03) - Ulepszenia Dokumentacji
### Dodano
- **Instrukcja pozyskiwania kluczy**: Dodano do `README.md` nową, szczegółową sekcję "Skąd wziąć wymagane klucze?" z linkami i instrukcjami krok po kroku.
---
## v2.1 (2025-08-03) - Ulepszenia Dokumentacji
### Dodano
- **Instrukcja "Szybki Start"**: Dodano do `README.md` szczegółową sekcję, która krok po kroku prowadzi nowego użytkownika przez proces instalacji na świeżym serwerze.
---
## v2.0 (2025-08-03) - Pierwsza Duża Refaktoryzacja
### Dodano
- **Modularność Skryptu**: Wprowadzono obsługę podstawowych komend (`install`, `uninstall` itp.).
- **Idempotentność**: Skrypt zaczął sprawdzać stan systemu przed wykonaniem akcji.
- **Weryfikacja Systemu**: Skrypt zaczął weryfikować, czy jest uruchamiany na kompatybilnej dystrybucji.
- **Szablony Konfiguracji**: Konfiguracje usług zostały przeniesione do zewnętrznych plików w nowo utworzonym folderze `templates/`.
- **Opcjonalne Moduły**: Dodano możliwość włączania/wyłączania instalacji `Fail2ban`, `PostgreSQL`, `Loki` i `Restic`.
### Zmieniono
- **Struktura Projektu**: Dodano folder `templates` na pliki konfiguracyjne.
---
## v1.1 (2025-08-03) - Centralizacja Konfiguracji
### Dodano
- **Plik `CHANGELOG.md`**: Zainicjowano dziennik zmian.
- **Plik `autoscript.conf.example`**: Stworzono szablon konfiguracyjny, aby ułatwić wdrożenie.
### Zmieniono
- **Refaktoryzacja Konfiguracji**: Zastąpiono zmienne środowiskowe dedykowanym plikiem `autoscript.conf`, co znacząco uprościło zarządzanie.
---
## v1.0 (2025-08-03) - Wersja Początkowa
### Dodano
- Początkowa wersja skryptu `start.sh` do automatyzacji serwera.
- Podstawowa dokumentacja `README.md`.
- Plik `.gitattributes` do normalizacji końca linii.

138
README.md
View file

@ -1,46 +1,85 @@
# AutoScript v3 - Zautomatyzowana Platforma do Zarządzania Serwerem
## 1. Przegląd
<p align="center">
<img src="https://img.shields.io/badge/version-3.0-blue.svg" alt="Version">
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
<img src="https://img.shields.io/badge/platform-Debian%2FUbuntu-orange.svg" alt="Platform">
</p>
AutoScript v3 to ewolucja prostego skryptu w kierunku w pełni modularnej platformy do automatyzacji i zarządzania cyklem życia serwera aplikacyjnego. Narzędzie jest zaprojektowane wokół architektury opartej na komendach, co pozwala na precyzyjne, bezpieczne i idempotentne operacje - od wstępnej konfiguracji po codzienne zarządzanie i deinstalację.
---
## 2. Kluczowe Koncepcje Architektoniczne
## 1. Filozofia i Cele Projektu
- **Modularność i Komendy**: Zamiast jednego, monolitycznego przebiegu, każdą operację wykonuje się dedykowaną komendą (np. `./start.sh deploy_traefik`).
- **Idempotentność i Paragony (Receipts)**: Skrypt śledzi ukończone instalacje. Można go bezpiecznie uruchamiać wielokrotnie - zainstaluje tylko brakujące elementy.
- **Walidacja "Pre-flight"**: Komenda `validate` sprawdza poprawność konfiguracji *przed* dokonaniem jakichkolwiek zmian w systemie.
- **Bezpieczeństwo jako Priorytet**: Wbudowane wzmacnianie zabezpieczeń, zarządzanie sekretami i przygotowanie pod zaawansowane techniki (AppArmor).
AutoScript narodził się z potrzeby stworzenia zautomatyzowanego, bezpiecznego i powtarzalnego procesu konfiguracji serwera. Ręczne przygotowywanie serwera jest czasochłonne i podatne na błędy. Ten projekt ma na celu rozwiązanie tych problemów, kierując się trzema głównymi zasadami:
## 3. Dostępne Komendy
1. **Automatyzacja ponad wszystko**: Wszystko, co można zautomatyzować, powinno być zautomatyzowane. Od instalacji pakietów, przez hardening systemu, po wdrożenie aplikacji.
2. **Bezpieczeństwo Domyślnie (Secure by Default)**: Skrypt wdraża najlepsze praktyki bezpieczeństwa od samego początku, nie jako opcję. Użytkownik nie musi być ekspertem od bezpieczeństwa, aby mieć dobrze zabezpieczony serwer.
3. **Idempotentność i Niezawodność**: Skrypt można bezpiecznie uruchamiać wielokrotnie. Zawsze doprowadzi system do z góry określonego, pożądanego stanu, instalując tylko brakujące elementy i nie psując istniejących.
Wszystkie komendy należy uruchamiać z uprawnieniami roota, np. `sudo ./start.sh <komenda>`.
## 2. Kluczowe Funkcje w Pigułce
| Komenda | Opis |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `install` | **Główna instalacja.** Uruchamia walidację i wdraża wszystkie podstawowe moduły. |
| `validate` | Sprawdza poprawność pliku `autoscript.conf` i połączeń z zewnętrznymi API. |
| `deploy_mastodon` | (W przygotowaniu) Wdraża i konfiguruje aplikację Mastodon. |
| `deploy_traefik` | Wdraża i konfiguruje reverse proxy Traefik. |
| `deploy_monitoring` | Wdraża stos monitoringu (Prometheus, Grafana, Alertmanager). |
| `secrets:edit <nazwa>` | Otwiera zaszyfrowany plik z sekretami dla danej usługi w edytorze. |
| `secrets:view <nazwa>` | Wyświetla odszyfrowaną zawartość pliku z sekretami. |
| `self-update` | Aktualizuje skrypt AutoScript do najnowszej wersji z repozytorium Git. |
| `uninstall` | **Niebezpieczne!** Usuwa wszystkie komponenty, dane i konfiguracje stworzone przez skrypt. |
| `help` | Wyświetla listę dostępnych komend. |
- **Pełna Konfiguracja Systemu**: Od zera do gotowego serwera za pomocą jednej komendy.
- **Modularna Architektura**: Zarządzaj poszczególnymi komponentami (Traefik, Monitoring) za pomocą dedykowanych komend.
- **Hardening Systemu**: Wzmacnianie zabezpieczeń SSH, firewall UFW, `CrowdSec`, `Fail2ban`.
- **Środowisko Kontenerowe**: Wdrożenie Dockera z `userns-remap` i Traefikiem jako reverse proxy.
- **Automatyczne Certyfikaty SSL**: Integracja Traefika z Let's Encrypt i Cloudflare.
- **Zintegrowany Monitoring**: Pełny stos monitoringu (Prometheus, Grafana, Alertmanager) i logów (Loki).
- **Bezpieczne Zarządzanie Sekretami**: Szyfrowanie wszystkich wrażliwych danych (kluczy API, haseł) za pomocą `sops`.
- **Walidacja Konfiguracji**: Sprawdzanie poprawności ustawień przed wprowadzeniem zmian w systemie.
- **Czysta Deinstalacja**: Możliwość bezpiecznego wycofania wszystkich zmian.
## 4. Instalacja Krok po Kroku
## 3. Architektura i Główne Koncepcje
Zrozumienie tych kilku koncepcji jest kluczowe, aby w pełni wykorzystać moc AutoScript.
- **Modularność i Komendy**: Zamiast jednego, monolitycznego skryptu, AutoScript jest sterowany komendami. Każda komenda odpowiada za konkretny, logiczny blok (np. `deploy_traefik`). Daje to pełną kontrolę nad cyklem życia serwera.
- **Idempotentność i Mechanizm "Paragonów"**: Po pomyślnym zakończeniu każdej dużej operacji (np. instalacji Traefika), skrypt tworzy w folderze `/opt/services/.receipts` pusty plik-znacznik (np. `.receipt_traefik`). Przed uruchomieniem jakiejkolwiek operacji, skrypt sprawdza obecność tego "paragonu". Jeśli paragon istnieje, operacja jest pomijana. To gwarantuje, że skrypt nie zepsuje istniejącej konfiguracji i można go bezpiecznie uruchamiać wielokrotnie.
- **Walidacja Konfiguracji ("Pre-flight Check")**: Komenda `validate` to Twoja siatka bezpieczeństwa. Zanim `install` dokona jakiejkolwiek zmiany, `validate` sprawdza, czy klucz API Cloudflare działa, czy domena jest poprawna, czy klucz SSH ma właściwy format itp. To zapobiega błędom w połowie instalacji.
- **Zarządzanie Sekretami (`sops`)**: Żadne hasła, tokeny ani klucze API nie są przechowywane na dysku jako jawny tekst. Wszystkie są szyfrowane w plikach z rozszerzeniem `.sops` przy użyciu klucza `age` generowanego przy pierwszym uruchomieniu. Skrypt automatycznie odszyfrowuje je w pamięci tylko wtedy, gdy są potrzebne.
## 4. Przewodnik po Konfiguracji (`autoscript.conf`)
To serce całego projektu. Poniżej znajduje się szczegółowy opis każdej zmiennej.
| Zmienna | Opis |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **SEKCJA WYMAGANA** | **Te wartości MUSZĄ być poprawnie ustawione.** |
| `PUBLIC_KEY` | Twój publiczny klucz SSH (zawartość pliku `~/.ssh/id_ed25519.pub`). Niezbędny do logowania po rekonfiguracji SSH. |
| `CF_DNS_API_TOKEN` | Token API z Cloudflare z uprawnieniami `Zone:DNS:Edit` dla Twojej domeny. |
| **USTAWIENIA GŁÓWNE** | |
| `PRIMARY_DOMAIN` | Główna domena, na której będzie działać główna aplikacja (np. Mastodon). Przykład: `social.ovh`. |
| `SERVICES_DOMAIN` | Domena dla usług pomocniczych (Grafana, Prometheus). Domyślnie jest to ta sama co `PRIMARY_DOMAIN`. |
| `ADMIN_EMAIL` | Adres e-mail używany do powiadomień od Let's Encrypt i alertów systemowych. |
| `TIMEZONE` | Strefa czasowa serwera, np. `Europe/Warsaw`. |
| **MODUŁY OPCJONALNE** | Włącz (`true`) lub wyłącz (`false`) instalację dodatkowych komponentów. |
| `INSTALL_FAIL2BAN` | Instaluje Fail2ban jako dodatkową warstwę ochrony. Zalecane. |
| `INSTALL_DATABASE` | Wdraża kontener z bazą danych PostgreSQL. Wymagane przez wiele aplikacji, w tym Mastodon. |
| `INSTALL_LOKI` | Wdraża system centralnego zbierania logów Loki. Bardzo przydatne do debugowania. |
| `INSTALL_BACKUP` | Konfiguruje system kopii zapasowych Restic. Wymaga ręcznego uzupełnienia danych dostępowych do chmury. |
| `ENABLE_APPARMOR` | (Eksperymentalne) Włącza generowanie profili bezpieczeństwa AppArmor dla kontenerów. |
| **POZOSTAŁE SEKCJE** | |
| `ALERT_SMTP_*` | Pełna konfiguracja serwera SMTP do wysyłania alertów z monitoringu. |
| `POSTGRES_PASSWORD` | Hasło dla bazy danych. Jeśli pozostawione puste, zostanie wygenerowane losowe. |
| `BACKUP_*` | Pełna konfiguracja dla Restic, w tym dane dostępowe do repozytorium w chmurze. |
| `*_VER` | Wersje obrazów Docker. Pozwala "przypiąć" konkretne wersje oprogramowania dla zapewnienia stabilności. |
## 5. Instalacja i Użycie
### Szybki Start (Instalacja na Nowym Serwerze)
1. **Zaloguj się jako `root` na nowym serwerze (Debian/Ubuntu).**
2. **Zainstaluj `git` i sklonuj repozytorium:**
```bash
apt update && apt install -y git
git clone https://github.com/pawelorzech/autoscript.git
cd autoscript
git clone https://github.com/pawelorzech/autoscript.git && cd autoscript
```
3. **Skonfiguruj AutoScript:**
```bash
cp autoscript.conf.example autoscript.conf
nano autoscript.conf # Wypełnij wszystkie zmienne
nano autoscript.conf # Wypełnij wszystkie zmienne zgodnie z przewodnikiem powyżej
```
4. **Sprawdź poprawność konfiguracji:**
```bash
@ -51,8 +90,51 @@ Wszystkie komendy należy uruchamiać z uprawnieniami roota, np. `sudo ./start.s
sudo ./start.sh install
```
## 5. Co dalej?
### Szczegółowy Opis Komend
Po zakończeniu instalacji, Twój serwer jest w pełni skonfigurowany i zabezpieczony. Zapoznaj się z krokami opisanymi w poprzednich wersjach `README` (zmiana portu SSH, logowanie jako `admin`, konfiguracja 2FA), ponieważ te zasady wciąż obowiązują.
| Komenda | Opis |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `install` | Meta-komenda, która uruchamia w odpowiedniej kolejności wszystkie niezbędne moduły instalacyjne. Idealna na start. |
| `validate` | Sprawdza poprawność pliku konfiguracyjnego i połączeń z zewnętrznymi API (np. Cloudflare). Nie wprowadza żadnych zmian. |
| `deploy_mastodon` | (W przygotowaniu) W pełni automatyzuje wdrożenie i konfigurację aplikacji Mastodon. |
| `deploy_traefik` | Wdraża i konfiguruje reverse proxy Traefik. |
| `deploy_monitoring` | Wdraża pełny stos monitoringu (Prometheus, Grafana, Alertmanager) i logowania (Loki). |
| `secrets:edit <nazwa>` | Bezpiecznie otwiera zaszyfrowany plik z sekretami dla danej usługi (np. `traefik`) w domyślnym edytorze. |
| `secrets:view <nazwa>` | Bezpiecznie wyświetla odszyfrowaną zawartość pliku z sekretami. |
| `self-update` | Aktualizuje skrypt AutoScript do najnowszej wersji z repozytorium Git. |
| `uninstall` | **BARDZO NIEBEZPIECZNE!** Usuwa wszystkie komponenty, dane i konfiguracje stworzone przez skrypt, bazując na zapisanych paragonach. |
Możesz teraz zacząć wdrażać właściwą aplikację, np. używając (w przyszłości) komendy `sudo ./start.sh deploy_mastodon`.
## 6. Aspekty Bezpieczeństwa
AutoScript traktuje bezpieczeństwo jako fundamentalny element, a nie dodatek.
- **Hardening Systemu**: Skrypt automatycznie zmienia domyślny port SSH, blokuje logowanie na konto `root`, wyłącza logowanie hasłem (wymuszając użycie kluczy SSH) i konfiguruje uwierzytelnianie dwuetapowe (TOTP) dla komendy `sudo`.
- **Firewall (UFW)**: Konfigurowana jest zapora sieciowa, która domyślnie blokuje cały ruch przychodzący, otwierając tylko niezbędne porty (SSH, HTTP/S, poczta).
- **Ochrona przed Włamaniami**: Instalowany jest `CrowdSec` (nowoczesny, oparty na reputacji IPS) oraz opcjonalnie `Fail2ban` (klasyczna ochrona logów).
- **Bezpieczeństwo Kontenerów**: Docker jest konfigurowany z `userns-remap`, co mapuje użytkownika `root` wewnątrz kontenera na zwykłego użytkownika na hoście, znacząco ograniczając potencjalne szkody w razie "ucieczki" z kontenera.
- **Zarządzanie Sekretami**: Jak wspomniano, wszystkie wrażliwe dane są szyfrowane na dysku za pomocą `sops`.
## 7. Rozwiązywanie Problemów (Troubleshooting)
- **Instalacja nie powiodła się?** Pierwszym krokiem jest zawsze sprawdzenie pliku logu: `less /var/log/autoscript.log`. Zawiera on szczegółowe informacje o każdej operacji.
- **Błędy konfiguracyjne?** Uruchom `./start.sh validate`, aby upewnić się, że wszystkie ustawienia są poprawne.
- **Problem z certyfikatem SSL?** Upewnij się, że Twoja domena poprawnie wskazuje na adres IP serwera, a token Cloudflare ma odpowiednie uprawnienia.
## 8. Roadmapa i Przyszły Rozwój
AutoScript jest aktywnie rozwijany. Poniżej znajduje się lista planowanych funkcji, dla których przygotowano już fundamenty w kodzie:
- [ ] **Pełna implementacja `deploy_mastodon`**.
- [ ] **Dynamiczne odkrywanie usług** dla Prometheus na podstawie etykiet Docker.
- [ ] **Centralne logowanie dla hosta** (przesyłanie logów z `/var/log` do Loki).
- [ ] **Tryb interaktywnej konfiguracji** (`interactive_setup`).
- [ ] **Generowanie profili AppArmor** dla kluczowych kontenerów.
- [ ] **Zaawansowane komendy do zarządzania kopiami zapasowymi** (`backup:run`, `backup:restore`).
## 9. Kontrybucja
Pomysły, zgłoszenia błędów i pull requesty są mile widziane! Proszę tworzyć zgłoszenia (issues) w repozytorium GitHub, aby omówić większe zmiany.
## 10. Licencja
Projekt jest udostępniany na licencji MIT.