Aplikacja jako usługa systemd
Zbudujesz jednostkę systemd dla aplikacji webowej, ustawisz użytkownika, katalog roboczy, konfigurację środowiskową i polecenie Uvicorna oraz sprawdzisz uruchomienie i logi usługi.
1. Krótka teoria
Plik jednostki example-app.service opisuje, jak systemd ma zarządzać procesem aplikacji. Sekcja [Unit] zawiera opis i zależności kolejności uruchamiania. [Service] określa proces: User i Group ograniczają jego uprawnienia, WorkingDirectory ustawia katalog potrzebny do importu kodu, a EnvironmentFile wskazuje plik konfiguracji środowiskowej. ExecStart powinien używać bezpośredniej ścieżki do Uvicorna w venv i uruchamiać app.main:app na 127.0.0.1:8000. Restart=on-failure pozwala ponowić uruchomienie po nieoczekiwanym błędzie, ale nie naprawia złej konfiguracji. Sekcja [Install] z WantedBy=multi-user.target pozwala włączyć autostart. Po utworzeniu lub zmianie jednostki wykonuje się systemctl daemon-reload. Następnie można ją włączyć, uruchomić i kontrolować przez status oraz journalctl -u. Ta konfiguracja dotyczy aplikacji webowej; wcześniejsze ogólne zasady diagnostyki systemd nadal obowiązują.
2. Przykłady komend
/etc/systemd/system/example-app.service
Przykładowa jednostka uruchamiająca aplikację przez Uvicorn z venv.
[Unit]
Description=Example ASGI application
After=network.target
[Service]
User=example-app
Group=example-app
WorkingDirectory=/opt/example-app
EnvironmentFile=/opt/example-app/.env
ExecStart=/opt/example-app/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000
Restart=on-failure
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
Wczytuje definicję nowej lub zmienionej jednostki.
$ sudo systemctl daemon-reload
sudo systemctl enable example-app.service
Włącza automatyczne uruchamianie aplikacji podczas startu systemu.
$ sudo systemctl enable example-app.service
sudo systemctl start example-app.service
Uruchamia usługę aplikacji w bieżącej sesji systemu.
$ sudo systemctl start example-app.service
sudo systemctl restart example-app.service
Restartuje usługę po świadomej zmianie kodu lub konfiguracji.
$ sudo systemctl restart example-app.service
systemctl status example-app.service
Pokazuje stan usługi, PID procesu i ostatnie komunikaty.
$ systemctl status example-app.service
journalctl -u example-app.service -n 50 --no-pager
Wyświetla 50 ostatnich wpisów dziennika aplikacji.
$ journalctl -u example-app.service -n 50 --no-pager3. Zadanie praktyczne
example-app.service z trzema sekcjami. W [Service] ustaw User=example-app, Group=example-app, WorkingDirectory=/opt/example-app, EnvironmentFile=/opt/example-app/.env, ExecStart=/opt/example-app/venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000 oraz Restart=on-failure. Dodaj WantedBy=multi-user.target, wykonaj daemon-reload, włącz i uruchom usługę. Sprawdź status, logi oraz lokalną odpowiedź przez curl. Użyj wyłącznie aplikacji laboratoryjnej.
4. Typowe błędy
- Wskazanie globalnego Uvicorna zamiast programu z venv w ExecStart.
- Ustawienie katalogu roboczego, z którego nie można zaimportować modułu aplikacji.
- Uruchamianie usługi jako root mimo braku takiej potrzeby.
- Pominięcie daemon-reload po zmianie pliku jednostki.
- Założenie, że enable natychmiast uruchamia usługę.
- Restartowanie usługi bez przeczytania statusu i logów po błędzie.
- Nadanie użytkownikowi usługi braku dostępu do kodu lub pliku środowiskowego.
5. Podsumowanie
Jednostka systemd zamienia ręczne polecenie Uvicorna w zarządzaną usługę. Kluczowe pola to User, Group, WorkingDirectory, EnvironmentFile i ExecStart. Po zmianie jednostki trzeba wykonać daemon-reload, a autostart i bieżące uruchomienie kontroluje się oddzielnie. Stan procesu pokazuje systemctl status, a pełniejszą przyczynę problemu zwykle journalctl -u.