Firmowid to aplikacja dla małych firm w Polsce: faktury w KSeF (wystawianie i
pobieranie), automatyczne parowanie przelewów z bankiem (Open Banking),
ewidencja czasu pracy w projektach, urlopy, delegacje i płace.
Kod jest na licencji AGPL-3.0. Możesz uruchomić Firmowid na własnym
serwerze albo korzystać z wersji hostowanej na firmowid.pl
(plan Darmowy 0 zł, bez limitu faktur).
Note for English speakers: Firmowid is a web app for small Polish businesses: KSeF e-invoicing, automatic bank-to-invoice matching, time tracking, leave and payroll. Open source under AGPL-3.0. The product targets the Polish market, so this README is in Polish; the commands in Szybki start work as-is, and env.template documents the local configuration in English.
Co potrafi
Zrzuty pochodzą z lokalnej instalacji na danych testowych z seedów.
Chcesz pomóc?
Zapraszamy! Poprawki błędów, usprawnienia UX, dokumentacja i nowe pomysły są mile
widziane. Do pracy nad kodem nie potrzebujesz dostępu do infrastruktury
Alergeek Ventures: aplikacja działa lokalnie na danych testowych, a wszystkie
zewnętrzne integracje są opcjonalne.
- Masz pytanie albo pomysł? Załóż dyskusję.
- Widzisz błąd? Otwórz issue z krokami do odtworzenia.
- Chcesz coś zmienić? Zrób fork, branch i pull request do
main. Przy większej
zmianie najpierw opisz pomysł w issue lub dyskusji, żeby nie pracować na próżno.
- Podatności bezpieczeństwa zgłaszaj prywatnie, zgodnie z SECURITY.md.
Zanim wyślesz PR, przejrzyj Jak pracujemy: uruchom mix check
i nazwij commity według Conventional Commits.
Dwie rzeczy wymagają maintainera:
- PR z forka nie dostaje sekretów CI, więc pełne CI (tłumaczenia, build, jakość,
Docker) nie uruchomi się na nim. Maintainer przeniesie twój commit na branch w
repozytorium i tam uruchomi CI.
- Nowe i zmienione teksty widoczne w UI (Gettext) muszą mieć tłumaczenia w Accent,
zanim CI przejdzie. Dostęp do Accent mają maintainerzy, więc napisz w PR, które
teksty się zmieniły. Szczegóły: CI: snapshoty tłumaczeń.
Z czego jest zbudowany
| Katalog | Zawartość |
|---|
lib/firmowid | Domena i logika biznesowa (zasoby Ash: faktury, KSeF, finanse, płace…) |
lib/firmowid_web | Interfejs webowy (LiveView), ułożony według funkcji |
lib/firmowid_mcp | Serwer MCP dla asystentów AI |
lib/firmowid_ui | Komponenty UI wspólne dla przeglądarki i MCP |
priv/repo/seeds* | Dane testowe do lokalnego developmentu |
Testy leżą obok kodu, który testują (*_test.exs w lib/).
Szybki start (bez Infisical)
Ta ścieżka jest dla wszystkich spoza zespołu Alergeek Ventures. Zespół pobiera
wspólną konfigurację z Infisical (opis niżej);
tutaj generujesz ją lokalnie.
Potrzebujesz: Elixira i Erlanga w wersjach z .tool-versions, Node.js 26,
Dockera lub Podmana z compose oraz kilku paczek systemowych. Instrukcja jest w
sekcji Instalacja środowiska; na Nixie wystarczy
direnv allow.
1. Pobierz kod
git clone https://github.com/Alergeek-Ventures/firmowid.git
cd firmowid
(albo sklonuj swój fork).
2. Skonfiguruj lokalne zmienne
cp env.template .env.worktree
echo "SECRET_KEY_BASE=$(openssl rand -base64 48)" >> .env.worktree
echo "OAUTH2_SIGNING_SECRET=$(openssl rand -base64 48)" >> .env.worktree
echo "CLOAK_VAULT_KEY=$(openssl rand -base64 32)" >> .env.worktree
Klucze są generowane tylko dla twojej lokalnej bazy. .env.worktree jest w
.gitignore, więc nie trafi do repozytorium.
Następnie wyłącz Infisical w powłoce, w której uruchamiasz polecenia mix
(najwygodniej dopisz to do profilu powłoki):
export AV_SKIP_INFISICAL=1
Bez tej flagi aplikacja próbuje pobrać konfigurację z Infisical i kończy się
błędem. Flaga musi być ustawiona w środowisku powłoki; wpis w .env.worktree nie
zadziała, bo ten plik jest wczytywany dopiero po kroku Infisical.
3. Uruchom bazę danych, S3 i Gotenberga
docker compose -f local/compose.yml up -d # albo: podman compose -f local/compose.yml up -d
Usługi nasłuchują na portach 5433 (PostgreSQL), 4566 (S3) i 3000
(Gotenberg). Jeśli któryś jest zajęty, zmień go w .env.worktree (dla bazy
ustaw też DATABASE_URL) i przekaż te same DB_PORT, S3_PORT,
GOTENBERG_PORT do polecenia compose.
4. Zainstaluj zależności i przygotuj bazę
mix setup
mix setup pobiera zależności Elixira i npm, opublikowany katalog tłumaczeń
(bez klucza Accent), tworzy bazę, uruchamia migracje, seeduje dane testowe i
buduje assety. Pierwsze uruchomienie kompiluje całą aplikację i trwa kilka minut.
Tłumaczenia są pobierane dla bieżącego commita albo origin/main. W forku trzymaj
main zsynchronizowany z upstreamem, żeby taki snapshot istniał.
5. Włącz serwer
mix phx.server
Wejdź na localhost:4000, zaloguj się jako
[email protected] / kolejka123456 i otwórz
/development: znajdziesz tam pełny
przewodnik po danych testowych, kontrahentach, projektach i scenariuszach KSeF.
Wysłane maile zobaczysz w /mailbox.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
