init

2026-07-28 02:04:36 +03:30
commit a5aed05b98
31 changed files with 3500 additions and 0 deletions
@@ -0,0 +1,113 @@
+# Hamkar
+
+Hamkar is a small team presence tracker built for startups that work with the Persian (Solar Hijri/Shamsi) calendar. It ships as one Go binary with embedded HTMX templates and uses SQLite by default.
+
+## Included
+
+- Self-service account creation with email or username and a salted PBKDF2 password
+- Login with either email address or username
+- Optional Google and GitHub OAuth login
+- Admin-created username/password teammate accounts
+- Persistent light and dark modes with automatic system-theme detection
+- Vazirmatn as the default interface font
+- Office and remote check-in/check-out
+- Persian month calendar with attendance, approved leave, remote days, Fridays, and fixed Solar Hijri public holidays
+- Team day detail showing who is present, remote, absent, or expected at the office
+- Time-off and remote-day requests with a dependency-free Jalali date picker and typed Persian-date fallback
+- Admin approval/rejection with review notes
+- Excel-compatible UTF-8 CSV reports with both Persian and Gregorian dates
+- CSRF protection, secure session cookies, security headers, and role checks
+- Responsive UI with no JavaScript build step
+
+## Start locally
+
+Requirements: Go 1.26 or later.
+
+```bash
+cp .env.example .env
+go run ./cmd/server
+```
+
+The app listens at <http://localhost:8080>. On a fresh database, use:
+
+```text
+username: admin
+password: admin123
+```
+
+Set `INITIAL_ADMIN_PASSWORD` before the first start to replace the demo password. It is only read when creating an empty database. The database is created at `./data/teammate.db`.
+
+Environment files are not loaded automatically. Export values in your shell, use a process manager, or run:
+
+```bash
+set -a
+source .env
+set +a
+go run ./cmd/server
+```
+
+## OAuth
+
+Create OAuth applications with these callback URLs:
+
+```text
+http://localhost:8080/auth/github/callback
+http://localhost:8080/auth/google/callback
+```
+
+Set the matching client ID and secret in the environment. Provider buttons only appear when configured. For production, set `APP_BASE_URL` to the public HTTPS origin and `SESSION_SECURE=true`.
+
+## Production
+
+```bash
+go build -o teammate ./cmd/server
+APP_ADDR=:8080 DATABASE_PATH=/var/lib/teammate/teammate.db SESSION_SECURE=true ./teammate
+```
+
+Place a TLS reverse proxy such as Caddy or nginx in front of the binary. Back up the SQLite database and its WAL files together, or use SQLite's online backup command. The store is intentionally serialized to one connection, which is a good fit for a small startup deployment.
+
+## Docker
+
+The multi-stage image runs tests during the build, compiles a static Go binary, uses a non-root runtime user, persists SQLite under `/data`, and exposes a `/healthz` container health check.
+
+```bash
+docker build -t hamkar:local .
+docker run --rm -p 8080:8080 \
+  -e SESSION_SECURE=false \
+  -e INITIAL_ADMIN_PASSWORD='replace-this-password' \
+  -v hamkar-data:/data \
+  hamkar:local
+```
+
+## Gitea Actions
+
+The workflow under `.gitea/workflows/ci.yaml` is adapted from the Sana API pipeline. Pull requests build and test the container without publishing it. Pushes to `main` build and publish both `main` and immutable commit-SHA tags.
+
+Configure this repository secret:
+
+```text
+REG_PASS       Password for oci.reg.darano.ir
+```
+
+The registry username defaults to `admin`, and the image defaults to `oci.reg.darano.ir/personal/tracking-personel`. Change the workflow environment if the repository uses a different registry path.
+
+## Persian calendar behavior
+
+The application stores dates in ISO Gregorian form internally and converts at the UI boundary. This keeps SQL comparisons and exports straightforward while making the primary calendar and request input Solar Hijri. Request dates use `YYYY-MM-DD`, for example `1405-05-06`.
+
+Fixed national holidays are included. Lunar Islamic holidays move each year and should be added from an authoritative annual calendar before production use.
+
+## Development
+
+```bash
+make test
+make build
+```
+
+The main packages are:
+
+- `internal/jalali`: dependency-free Persian/Gregorian date conversion
+- `internal/app/store.go`: SQLite schema and data access
+- `internal/app/server.go`: HTTP routes, auth, workflows, and CSV export
+- `internal/app/templates`: embedded server-rendered views
+- `internal/app/static`: responsive application styling