Configuration

Ελληνικά · English

Ρυθμίσεις server (.env)

Όλες οι ρυθμίσεις του server βρίσκονται στο αρχείο .env (ξεκινήστε από το .env.example). Μετά από κάθε αλλαγή, επανεκκινήστε την εφαρμογή με cd ~/karta && docker compose up -d. Μην ανεβάσετε ποτέ το πραγματικό σας .env στο GitHub: περιέχει τον κωδικό του ΕΡΓΑΝΗ και κλειδιά.

Από τη σελίδα διαχείρισης: η λειτουργία (ERGANI_MODE), το ΑΦΜ, το παράρτημα, ο κωδικός εργοδότη στο QR του ΕΡΓΑΝΗ (ERGANI_EMPLOYER_ID), το σύστημα δήλωσης υπερωριών (TIME_DECLARATION), οι χρήστες του ΕΡΓΑΝΗ και οι ειδοποιήσεις στο κινητό (NTFY_*) ρυθμίζονται και στις «Ρυθμίσεις» της σελίδας διαχείρισης, χωρίς επανεκκίνηση. Ό,τι αποθηκεύεται εκεί υπερισχύει του .env (η σελίδα γράφει «από το .env» δίπλα σε ό,τι έρχεται από εδώ). Άρα, αν μια τιμή έχει αποθηκευτεί στη σελίδα, η αλλαγή της στο .env δεν αλλάζει τίποτα. Οι κωδικοί που αποθηκεύονται εκεί κρυπτογραφούνται με το PIN_KEY.

Οι κανόνες της καθημερινής λειτουργίας, όπως ευελιξία, προθεσμία υπερωρίας και εβδομαδιαία όρια, δεν ρυθμίζονται εδώ. Βρίσκονται στη σελίδα διαχείρισης, στο «Ρυθμίσεις» → «Όρια και ειδοποιήσεις».

ΕΡΓΑΝΗ

Μεταβλητή	Υποχρεωτική	Τι σημαίνει
ERGANI_MODE	όχι (προεπιλογή dry_run)	dry_run, trial ή production. Δείτε Έναρξη κανονικής λειτουργίας. Η διεύθυνση του ΕΡΓΑΝΗ προκύπτει από τη λειτουργία· μην τη ρυθμίσετε μόνοι σας.
ERGANI_USERNAME / ERGANI_PASSWORD	για production (και για να φέρετε το προσωπικό)	Ο χρήστης web services της επιχείρησης στο ΕΡΓΑΝΗ.
ERGANI_USER_TYPE	όχι (προεπιλογή 01)	01 = χρήστης API / εξωτερικός χρήστης, 02 = χρήστης «ΕΡΓΑΝΗ» από τους «Εξωτερικούς Χρήστες Παραρτημάτων».
ERGANI_TRIAL_USERNAME / ERGANI_TRIAL_PASSWORD	όχι	Χρήστης του δοκιμαστικού περιβάλλοντος του ΕΡΓΑΝΗ (trialv2eservices.yeka.gr, σύνδεση με TaxisNet του εργοδότη). Αν τα αφήσετε κενά, στο trial χρησιμοποιείται ο κανονικός χρήστης (ERGANI_USERNAME).
ERGANI_TRIAL_USER_TYPE	όχι (προεπιλογή 02)	Όπως παραπάνω, για τον δοκιμαστικό χρήστη.
EMPLOYER_AFM	για trial / production	Το ΑΦΜ του εργοδότη (9 ψηφία).
BRANCH_NUMBER	όχι (προεπιλογή 0)	Ο αριθμός παραρτήματος (Α/Α παραρτήματος).
TIME_DECLARATION	όχι	advance (προαναγγελία, προεπιλογή) ή retro (απολογιστικό σύστημα): πώς δηλώνει η επιχείρηση στο ΕΡΓΑΝΗ αλλαγές ωραρίου και υπερωρίες. Δείτε Ρυθμίσεις.
ERGANI_EMPLOYER_ID	όχι	Ο κωδικός σας μέσα στο QR εργαζομένου του ΕΡΓΑΝΗ (το id:). Όταν οριστεί, η οθόνη του καταστήματος δεν δέχεται QR ΕΡΓΑΝΗ άλλου εργοδότη.

Στο dry_run δεν υποβάλλεται ποτέ τίποτα. Οι υπηρεσίες ανάγνωσης που χρησιμοποιεί ο «Έλεγχος ΕΡΓΑΝΗ» (εργοδότης, παραρτήματα, προσωπικό) χρησιμοποιούν ωστόσο το πραγματικό ΕΡΓΑΝΗ, μόνο για ανάγνωση. Άρα χρειάζεστε τον πραγματικό χρήστη για να φέρετε το προσωπικό, ακόμα και στις δοκιμές.

Πρόσβαση διαχειριστή (Cloudflare Access)

Μεταβλητή	Υποχρεωτική	Τι σημαίνει
CF_ACCESS_TEAM_DOMAIN	ναι	Το team domain σας στο Cloudflare Zero Trust, χωρίς https://, π.χ. yourteam.cloudflareaccess.com.
CF_ACCESS_AUD	ναι	Το Audience (AUD) tag της εφαρμογής Access που προστατεύει το /admin.
ADMIN_EMAILS	ναι	Τα email που επιτρέπεται να μπουν στη σελίδα διαχείρισης, χωρισμένα με κόμμα. Πρέπει να ταιριάζουν με την πολιτική του Access.

Εφαρμογή

Μεταβλητή	Προεπιλογή	Τι σημαίνει
PUBLIC_ORIGIN	http://localhost:8000	Η δημόσια διεύθυνση της Karta σας, π.χ. https://karta.tokatastimamou.gr. Χρησιμοποιείται για να ελέγχεται από πού έρχονται τα αιτήματα και για τους συνδέσμους κάρτας στο κινητό. Ορίστε την στην κανονική λειτουργία.
DB_PATH	/data/workcard.db	Η θέση της βάσης SQLite.
LATE_THRESHOLD_SECONDS	120	Αν ένα χτύπημα φτάσει στο ΕΡΓΑΝΗ αργότερα από τόσα δευτερόλεπτα μετά τη στιγμή που έγινε (π.χ. μετά από διακοπή του internet), στέλνεται ως εκπρόθεσμη δήλωση με αιτιολογία. Δείτε Πώς φτάνουν τα χτυπήματα στο ΕΡΓΑΝΗ.
DEBOUNCE_SECONDS	60	Ελάχιστος χρόνος ανάμεσα σε δύο χτυπήματα του ίδιου ατόμου, ώστε να μη γίνονται κατά λάθος διπλά.

Ώρα: η Karta δουλεύει πάντα σε ώρα Ελλάδας (Europe/Athens), μαζί με τις αλλαγές θερινής και χειμερινής ώρας, ό,τι ζώνη ώρας κι αν έχει ο server σας. Δεν χρειάζεται να αλλάξετε τίποτα· το TZ στο docker-compose.yml επηρεάζει μόνο την ώρα στα logs.

Ειδοποιήσεις στο κινητό (προαιρετικά)

Η Karta στέλνει ειδοποιήσεις στο κινητό σας μέσω του ntfy: εγκαταστήστε την εφαρμογή ntfy και εγγραφείτε στο θέμα (topic) σας. Αν τα αφήσετε κενά, οι ειδοποιήσεις στο κινητό απενεργοποιούνται και εμφανίζονται μόνο στη σελίδα διαχείρισης.

Μεταβλητή	Τι σημαίνει
NTFY_URL	Ο server του ntfy, π.χ. https://ntfy.sh ή δικός σας.
NTFY_TOPIC	Το όνομα του θέματος. Αν χρησιμοποιείτε τον δημόσιο server, διαλέξτε κάτι μακρύ και τυχαίο.
NTFY_TOKEN	Κλειδί πρόσβασης, αν το ζητά ο server σας.

Κλειδί κρυπτογράφησης (PIN_KEY)

Μεταβλητή	Τι σημαίνει
PIN_KEY	Κλειδί 32 bytes. Το γράφει ο οδηγός ρύθμισης. Αν στήνετε χειροκίνητα, δημιουργήστε το μία φορά με python3 -c "import os,base64;print(base64.urlsafe_b64encode(os.urandom(32)).decode())".

Το PIN_KEY χρειάζεται, δεν είναι προαιρετικό. Με αυτό:

• η σελίδα διαχείρισης φυλάει κρυπτογραφημένα τον κωδικό του ΕΡΓΑΝΗ και το κλειδί του ntfy· χωρίς αυτό, αυτοί οι κωδικοί μπαίνουν μόνο στο .env·
• η σελίδα διαχείρισης δείχνει τα τρέχοντα PIN και τις κάρτες QR των εργαζομένων·
• φτιάχνεται ο σύνδεσμος για την κάρτα QR στο κινητό.

Χωρίς PIN_KEY, τα PIN αποθηκεύονται μόνο ως μη αναστρέψιμη σύνοψη (hash) και δεν μπορούν να εμφανιστούν ξανά· μπορείτε μόνο να ορίσετε νέο. Αν χάσετε το κλειδί:

• τα PIN και οι κάρτες QR συνεχίζουν να λειτουργούν, αλλά δεν εμφανίζονται μέχρι να δώσετε σε κάθε εργαζόμενο νέο PIN («Νέο PIN») ή νέα κάρτα·
• ο κωδικός του ΕΡΓΑΝΗ και το κλειδί του ntfy που είχαν αποθηκευτεί στη σελίδα διαχείρισης δεν διαβάζονται πια· πρέπει να τα ξαναγράψετε στις «Ρυθμίσεις».

Το PIN_KEY ταξιδεύει κρυπτογραφημένο μέσα σε κάθε αντίγραφο στο cloud, και μια επαναφορά από το cloud σε νέο μηχάνημα το χρησιμοποιεί αυτόματα (το κρατά στο pin-key, δίπλα στη βάση). Αν δεν έχετε αντίγραφα στο cloud, κρατήστε ένα αντίγραφο του .env (ή τουλάχιστον του PIN_KEY) σε ασφαλές μέρος. Δείτε Αντίγραφα ασφαλείας.

Έκδοση

Μεταβλητή	Τι σημαίνει
KARTA_VERSION	Η έκδοση της Karta που ξεκινά το docker-compose.yml, π.χ. 1.5.0. Τη γράφει ο οδηγός ρύθμισης και την αλλάζει το «Ενημέρωση τώρα» (ή το ./setup.sh update). Αν η νέα έκδοση δεν ξεκινήσει σωστά μέσα σε δύο λεπτά, γράφεται ξανά η προηγούμενη και η Karta επιστρέφει σε αυτήν. Χωρίς τιμή: η τελευταία έκδοση (latest).

Cloudflare Tunnel

Μεταβλητή	Τι σημαίνει
COMPOSE_PROFILES	tunnel: το docker compose ξεκινά και το tunnel μαζί με την Karta (το γράφει ο οδηγός ρύθμισης). Χωρίς αυτό ξεκινά μόνο η Karta, για δικό σας reverse proxy.
TUNNEL_TOKEN	Το token του tunnel (το γράφει ο οδηγός ρύθμισης).
TUNNEL_PROTOCOL	Πώς συνδέεται το tunnel: http2 για μηχάνημα στο κατάστημα ή στο σπίτι (σταθερό πίσω από router σπιτιού), auto σε VPS (QUIC/HTTP/3 με HTTP/2 αν χρειαστεί). Προεπιλογή http2. Μόνο με το docker-compose.yml.