From cc30aa668c4327c0b66222670b8d8045f5ef5990 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Orzech?= Date: Sun, 3 Aug 2025 13:06:21 +0200 Subject: [PATCH] readme update --- CHANGELOG.md | 17 ------ README.md | 144 +++++++++++++++++++-------------------------------- 2 files changed, 52 insertions(+), 109 deletions(-) delete mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 6139d21..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,17 +0,0 @@ -# Changelog - -## v4.0 (2025-08-03) - Pełna Implementacja Funkcji - -### Dodano - -- **Pełna implementacja `deploy_mastodon`**: Komenda teraz w pełni automatyzuje wdrożenie Mastodona, włącznie z generowaniem sekretów, konfiguracji i migracjami bazy danych. -- **Dynamiczne odkrywanie usług Prometheus**: Prometheus został skonfigurowany do automatycznego monitorowania kontenerów na podstawie etykiet Docker, co eliminuje potrzebę ręcznej edycji konfiguracji. -- **Centralne logowanie dla hosta**: Promtail został skonfigurowany do zbierania logów nie tylko z kontenerów, ale również z kluczowych plików systemowych (`/var/log`), co daje pełny obraz zdarzeń w systemie. -- **Zaimplementowano puste funkcje (stubs)** dla `interactive-setup`, `backup:*` i `self-update`, przygotowując grunt pod ich przyszłą, pełną implementację. - -### Zmieniono - -- **Struktura Monitoringu**: Przebudowano konfigurację `prometheus.yml` i `docker-compose.yml` w folderze `templates/monitoring`, aby wspierać dynamiczne odkrywanie usług. -- **Struktura Projektu**: Dodano folder `templates/mastodon` z szablonami dla `docker-compose.yml` i `.env.production`. - -(Poprzednie wersje poniżej) diff --git a/README.md b/README.md index 5868b42..e3b8c4a 100644 --- a/README.md +++ b/README.md @@ -1,74 +1,54 @@ -# AutoScript v3 - Zautomatyzowana Platforma do Zarządzania Serwerem -

- Version - License - Platform + + AutoScript Version + + + License + + + Platform +

+

AutoScript: Zautomatyzowana Platforma Mastodon

+ +**AutoScript to w pełni zautomatyzowane, bezpieczne i gotowe do użycia rozwiązanie do wdrażania i zarządzania serwerem Mastodon oraz jego kompletnym środowiskiem.** Zapomnij o ręcznej konfiguracji – ten projekt przekształca "surowy" serwer w gotową do pracy, zabezpieczoną i monitorowaną platformę za pomocą kilku prostych komend. + --- -## 1. Filozofia i Cele Projektu +## Spis Treści -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: +1. [Filozofia Projektu](#1-filozofia-projektu) +2. [Kluczowe Funkcje](#2-kluczowe-funkcje) +3. [Architektura w Pigułce](#3-architektura-w-pigułce) +4. [Instalacja (Szybki Start)](#4-instalacja-szybki-start) +5. [Przewodnik po Komendach](#5-przewodnik-po-komendach) +6. [Licencja](#6-licencja) -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. +--- -## 2. Kluczowe Funkcje w Pigułce +## 1. Filozofia Projektu -- **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. +- **Automatyzacja ponad wszystko**: Od instalacji pakietów, przez hardening systemu, po wdrożenie Mastodona – wszystko jest zautomatyzowane. +- **Bezpieczeństwo Domyślnie (Secure by Default)**: Wdrażamy najlepsze praktyki bezpieczeństwa od samego początku, nie jako opcję. +- **Idempotentność i Niezawodność**: Skrypt można bezpiecznie uruchamiać wielokrotnie. Zawsze doprowadzi system do pożądanego stanu. + +## 2. Kluczowe Funkcje + +- **Automatyczne Wdrożenie Mastodona**: Pełna instalacja i konfiguracja Mastodona, włącznie z bazą danych i Redis. +- **Hardening Systemu**: Wzmacnianie zabezpieczeń SSH, firewall UFW, `CrowdSec` i `Fail2ban`. +- **Zintegrowany Monitoring i Logowanie**: Pełny stos monitoringu (Prometheus, Grafana) i logów (Loki, Promtail) z automatycznym odkrywaniem usług. - **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`. +- **Bezpieczne Zarządzanie Sekretami**: Szyfrowanie wszystkich wrażliwych danych za pomocą `sops`. - **Walidacja Konfiguracji**: Sprawdzanie poprawności ustawień przed wprowadzeniem zmian w systemie. -- **Czysta Deinstalacja**: Możliwość bezpiecznego wycofania wszystkich zmian. -## 3. Architektura i Główne Koncepcje +## 3. Architektura w Pigułce -Zrozumienie tych kilku koncepcji jest kluczowe, aby w pełni wykorzystać moc AutoScript. +- **Modularność**: Każdą operację wykonuje się dedykowaną komendą (np. `./start.sh deploy_traefik`). +- **Idempotentność**: Skrypt śledzi ukończone instalacje. Można go bezpiecznie uruchamiać wielokrotnie. +- **Walidacja "Pre-flight"**: Komenda `validate` sprawdza poprawność konfiguracji *przed* dokonaniem jakichkolwiek zmian. -- **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) +## 4. Instalacja (Szybki Start) 1. **Zaloguj się jako `root` na nowym serwerze (Debian/Ubuntu).** 2. **Zainstaluj `git` i sklonuj repozytorium:** @@ -79,7 +59,7 @@ To serce całego projektu. Poniżej znajduje się szczegółowy opis każdej zmi 3. **Skonfiguruj AutoScript:** ```bash cp autoscript.conf.example autoscript.conf - nano autoscript.conf # Wypełnij wszystkie zmienne zgodnie z przewodnikiem powyżej + nano autoscript.conf # Wypełnij wszystkie zmienne ``` 4. **Sprawdź poprawność konfiguracji:** ```bash @@ -90,40 +70,20 @@ To serce całego projektu. Poniżej znajduje się szczegółowy opis każdej zmi sudo ./start.sh install ``` -### Szczegółowy Opis Komend +## 5. Przewodnik po Komendach -| 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 ` | Bezpiecznie otwiera zaszyfrowany plik z sekretami dla danej usługi (np. `traefik`) w domyślnym edytorze. | -| `secrets:view ` | 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. | +| 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` | 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 ` | Otwiera zaszyfrowany plik z sekretami dla danej usługi w edytorze. | +| `secrets:view ` | 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. | -## 6. Aspekty Bezpieczeństwa +## 6. Licencja -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. 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. \ No newline at end of file +Projekt jest udostępniany na licencji MIT.