taxmachine.pl

Strefa klienta na serwerze Linux — instalacja i obsługa

Opublikowano

Strefa klienta może działać zamiast usługi Windows na serwerze z Debianem albo Ubuntu — na zwykłym serwerze, w maszynie wirtualnej albo w kontenerze Proxmoxa. Program TaxMachine zostaje na komputerach biura bez zmian; na Linuksie działa tylko Strefa, połączona z tą samą bazą MariaDB/MySQL.

Na Linuksie Strefą zarządza jedno polecenie: tm-strefa. Instaluje ją, dodaje instancję dla bazy, pokazuje stan i co noc sama pobiera nowe wersje — bez ręcznej aktualizacji, której wymaga usługa Windows.

Dostępność. Strefa klienta na Linuksie jest w wydaniu 3.6846 (29 października 2026) i nowszych. Pole Adres Strefy klienta w opcjach bazy, potrzebne przy Strefie na Linuksie, jest od wydania 3.6847.

Co jest potrzebne

  • Serwer z Debianem albo Ubuntu z systemd, 64-bitowy (x86_64), z dostępem do internetu (pobieranie Strefy i nocne aktualizacje). Sprawdzone na Debianie 13. W Proxmoxie wystarczy kontener LXC nieuprzywilejowany z włączonym nesting: 2 rdzenie, 2 GB pamięci, 16 GB dysku.
  • Dostęp do bazy danych programu z tego serwera — adres bazy z pliku konfiguracji musi być osiągalny, a użytkownik bazy musi mieć prawo łączenia się z adresu serwera.
  • Serwer pośredniczący z HTTPS (np. Nginx Proxy Manager), pod adresem, który widzą klienci — tak samo jak przy usłudze Windows.
  • Plik konfiguracji instancji (tmweb.json) z programu — opis niżej.

Pakiety systemowe (m.in. biblioteka ICU, czcionki do wydruków PDF, strefa czasowa) polecenie instaluje samo. Strefa jest kompletna, nie potrzebuje osobnej instalacji .NET.

Plik konfiguracji instancji

Program zapisuje plik przy instalacji Strefy w oknie Strefa klienta (wstążka Konfiguracja), osobno dla każdej bazy:

C:\ProgramData\TaxMachine\Approvals.Portal\instancje\<nazwa bazy>\tmweb.json

W pliku są połączenie z bazą, poczta wychodząca, port nasłuchu (domyślnie 5091) i ustawienia Strefy, m.in. sekret linków logowania. Są w nim hasła — przenieś go na serwer bezpiecznie (np. przez scp), nie wysyłaj pocztą.

Gdy Strefa działała dotąd jako usługa Windows, skopiuj plik tej bazy z komputera, na którym była zainstalowana.

Instalacja

Zaloguj się na serwer jako root i pobierz polecenie:

curl -fsSLO https://d.tmxp.pl/tm-strefa.sh

Zainstaluj Strefę:

bash tm-strefa.sh instaluj

Instalacja doinstalowuje pakiety, zakłada konto systemowe tm-strefa, pobiera najnowszą Strefę z serwera aktualizacji TaxMachine i włącza nocne aktualizacje. Od tej chwili polecenie tm-strefa jest dostępne w systemie.

Instancja dla bazy

Jedna instancja obsługuje jedną bazę programu. Nazwij ją jak bazę (małe litery, cyfry, - i _), np. biuro:

tm-strefa dodaj biuro /root/tmweb.json

Polecenie sprawdza połączenie z bazą i jej wersję, zapisuje konfigurację w /etc/tm-strefa/biuro/tmweb.json i od razu uruchamia Strefę. Plik źródłowy możesz potem usunąć z katalogu /root.

Jedna baza — jedna Strefa. Zanim dodasz instancję dla bazy, z której korzystała usługa Windows, zatrzymaj tę usługę. Dwie Strefy na tej samej bazie wysyłają klientom każdy mail dwa razy. Zobacz Przeniesienie z Windows.

Gdy baza jest starsza niż wymaga Strefa, polecenie wypisze, czego w niej brakuje — otwórz bazę aktualnym programem TaxMachine, wtedy akceptacje ruszą.

Serwer pośredniczący (HTTPS)

Strefa słucha na porcie z pliku konfiguracji (domyślnie 5091), bez szyfrowania. HTTPS, certyfikat i przekierowanie z http:// robi serwer pośredniczący. W Nginx Proxy Manager:

  1. Proxy Host z adresem Strefy (np. strefa.twojebiuro.pl), Forward: http://<adres serwera>:5091.

  2. Zaznacz Websockets Support — Strefa bez niego ładuje się, ale nie działa.

  3. Na zakładce SSL: certyfikat Let's Encrypt, Force SSL.

  4. Na zakładce Advanced limit przesyłanych plików (klienci dosyłają dokumenty) i dłuższe połączenia:

    proxy_read_timeout 120s;
proxy_send_timeout 120s;
client_max_body_size 20m;

Port 5091 nie powinien być osiągalny z internetu z pominięciem serwera pośredniczącego. Plik konfiguracji z programu ma już włączoną pracę za serwerem pośredniczącym, gdy adres publiczny zaczyna się od https://.

Adres Strefy klienta

Adres, pod którym klienci widzą Strefę (np. https://strefa.twojebiuro.pl), ustawiasz w programie: Opcje bazy danych → Opcje dla biur rachunkowych → Adres Strefy klienta. Program buduje z niego linki logowania („Otwórz Strefę klienta”, maile z linkiem) i łączy się ze Strefą przy wysyłce z programu.

Program używa nowego adresu od razu, a Strefa czyta go przy starcie — po zmianie uruchom ją ponownie:

systemctl restart tm-strefa@biuro

Poprzedni adres zostaw w serwerze pośredniczącym, żeby działały linki z wysłanych już maili.

Przy Strefie na Linuksie nie używaj przycisku „Zainstaluj / aktualizuj…” w oknie Strefa klienta w programie dla tej samej bazy — założyłby i uruchomił drugą Strefę jako usługę Windows.

Codzienna obsługa

Polecenia wpisujesz na serwerze jako root. W przykładach instancja nazywa się biuro.

PolecenieCo robi
tm-strefa stanwersja zainstalowana i dostępna na serwerze aktualizacji, poprzednia wersja, instancje (port, od kiedy działają), termin i wynik nocnej aktualizacji
tm-strefa aktualizujinstaluje nową wersję od razu, bez czekania do nocy
tm-strefa aktualizuj --wymusinstaluje także wersję odrzuconą wcześniej po nieudanym starcie
tm-strefa cofnijwraca do poprzedniej wersji
tm-strefa dodaj <instancja> <tmweb.json>nowa instancja albo podmiana konfiguracji istniejącej — od razu ją uruchamia
tm-strefa usun <instancja>zatrzymuje i usuwa instancję; baza danych zostaje bez zmian
tm-strefa pomockrótki opis poleceń
systemctl restart tm-strefa@biuroponowne uruchomienie Strefy (np. po zmianie adresu albo ustawień w opcjach bazy)
journalctl -u tm-strefa@biuro -flog Strefy na bieżąco (koniec: Ctrl+C)
journalctl -u tm-strefa-aktualizacjaco robiły nocne aktualizacje

Konfiguracja instancji jest w /etc/tm-strefa/<instancja>/tmweb.json, klucze logowania klientów w /var/lib/tm-strefa/<instancja>/klucze.

Aktualizacje

Strefa aktualizuje się sama, co noc między 3:30 a 4:30:

  • pobiera nową wersję z serwera aktualizacji TaxMachine i sprawdza jej sumę kontrolną;
  • czeka, gdy nowa Strefa wymaga nowszej bazy — do czasu, aż otworzysz bazę aktualnym programem; sprawdza to co noc;
  • uruchamia instancje ponownie (kilkanaście sekund przerwy; zalogowani klienci zostają zalogowani);
  • gdy nowa wersja nie wystartuje, sama wraca do poprzedniej i tej wersji już nie próbuje.

Na dysku zostają dwie wersje: bieżąca i poprzednia (tm-strefa cofnij). Wynik ostatniej aktualizacji pokazuje tm-strefa stan.

Przeniesienie z Windows

  1. Przygotuj serwer: instalacja, plik konfiguracji bazy skopiowany z komputera z usługą Windows, serwer pośredniczący gotowy (na razie bez przełączania).

  2. Na komputerze z usługą Windows zatrzymaj usługę TaxMachine - Strefa klienta (…) i ustaw jej typ uruchomienia na Wyłączony — „Ręczny” nie wystarczy, bo okno Strefa klienta w programie przy aktualizacji uruchamia usługę. W wierszu poleceń jako administrator (nazwa usługi to TMKSeFApprovalsPortal_ i nazwa bazy):

    sc config TMKSeFApprovalsPortal_biuro start= disabled

  3. Na Linuksie: tm-strefa dodaj biuro /root/tmweb.json.

  4. W serwerze pośredniczącym skieruj adres Strefy na http://<adres serwera Linux>:5091.

  5. Sprawdź logowanie do Strefy i link z ostatniego maila.

Klienci zalogują się raz od nowa — klucze logowania z Windows nie przechodzą na Linuksa. Usługę Windows zostaw wyłączoną na kilka tygodni na wypadek powrotu, potem odinstaluj ją w oknie Strefa klienta przyciskiem Odinstaluj….

Docker

Strefa jest też obrazem Dockera — na serwer, na którym biuro używa już Dockera. Aktualizacje obrazu są ręczne; na zwykłym Debianie i Ubuntu prościej jest użyć tm-strefa.

W osobnym katalogu (np. /opt/strefa), z plikiem konfiguracji tmweb.json obok:

curl -fsSLO https://d.tmxp.pl/strefa-docker.tar.gz && docker load -i strefa-docker.tar.gz

curl -fsSL https://d.tmxp.pl/strefa-compose.yaml -o compose.yaml

chown 1654:1654 tmweb.json && chmod 600 tmweb.json

docker compose run --rm strefa --command check-config

docker compose up -d

W kontenerze Strefa słucha na porcie 8080, na zewnątrz na 5091 (inny port: STREFA_PORT w pliku .env obok). Baza na tym samym komputerze: w pliku konfiguracji adres host.docker.internal. Aktualizacja: pobierz i wczytaj nowy plik obrazu jak wyżej, sprawdź konfigurację i ponownie docker compose up -d. Log: docker compose logs -f strefa.