Skip to content

TaskView is a self-hosted project and task management platform focused on clarity, ownership, and control. TaskView is built for teams that want a transparent, self-hosted alternative to SaaS task managers.

chore: docs

Nikolai Giman83979ac47ca7
diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.md
index 8bf046d..4dc7cec 100644
--- a/docs/1.getting-started/2.installation.md
+++ b/docs/1.getting-started/2.installation.md
@@ -144,6 +144,10 @@ services:
taskview-webapp:
image: gimanhead/taskview-ce-webapp:latest
restart: unless-stopped
+ environment:
+ # The web app will always use this API server and hide the server selector on the login page.
+ # Remove this variable if you want to pick the API server manually on the login page.
+ TASKVIEW_API_URL: "http://localhost:1725"
ports:
- "8888:80"
# Enable for realtime notification read https://taskview.tech/docs/configuration/environment-variables#centrifugo-configuration-file
@@ -175,14 +179,16 @@ Go to [http://localhost:8888](http://localhost:8888) in your browser. You'll see
### Configure the API server
-Before logging in, you need to tell the web app where the API server is running. Click the **server settings** icon on the login page and add the API server URL:
+The web app (port 8888) serves the frontend, while the API server (port 1725) handles authentication, projects, tasks, and all backend operations.
+
+If you set `TASKVIEW_API_URL` on the `taskview-webapp` service (as in the compose file above), there is nothing to configure — the web app already knows where the API is, and the server selector is hidden from the login page.
+
+Without `TASKVIEW_API_URL`, click the **server settings** section on the login page and add the API server URL manually:
```
http://localhost:1725
```
-This is the API server that handles authentication, projects, tasks, and all backend operations. The web app (port 8888) serves the frontend, while the API server (port 1725) handles the data.
-
### Log in with the default user
The database migration creates a default user so you can log in right away:
@@ -193,31 +199,25 @@ The database migration creates a default user so you can log in right away:
Use these credentials to verify that everything is working - check that the UI loads, you can create a project, add tasks, etc.
::callout{icon="i-lucide-alert-triangle" color="error"}
-**Important:** The default user is for initial setup only. Once you've confirmed the system works, delete the default user and create your own account with a secure password.
+**Important:** The default credentials are publicly known — anyone who has read this page can sign in to a fresh installation. Claim the account right after the first login.
::
-### Replacing the default user
-
-1. Log in with the default credentials
-2. Register a new account with your real email and a strong password
-3. Delete the default `admin` account
-
-If you prefer to create the first user directly in the database, generate a password hash:
+### Claim the default account
-```ts
-import { hashSync } from 'bcryptjs'
+Make the default account your own — no SMTP or database access needed:
-const passwordHash = hashSync('your-secure-password', 12)
-console.log(passwordHash)
-```
+1. Log in with the default credentials
+2. Open **Account settings** — the highlighted **Login and email** card is shown at the top (it is visible only to the default user)
+3. Set your own login, email and a strong password, confirm with the current password (`user1!#Q`), and click **Save and sign out**
+4. Sign in again with your new login and password
-Or as a one-liner:
+![The Login and email card in Account settings for claiming the default account](/taskview/change-def-account.png)
-```bash
-node -e "console.log(require('bcryptjs').hashSync('your-secure-password', 12))"
-```
+Your organizations, projects and permissions are preserved. Once the email is changed, the card disappears and the claim endpoint is disabled.
-Then insert the user into the database with the generated hash.
+::callout{icon="i-lucide-mail" color="info"}
+Changing the password later requires a confirmation code sent by email. If your installation has no SMTP, set `PASSWORD_CHANGE_CONFIRMATION="password"` in `.env.taskview` so password changes are confirmed with the current password instead. See [Environment Variables](/docs/configuration/environment-variables#authentication).
+::
## Updating
@@ -233,7 +233,8 @@ The migration container will automatically apply any new database changes on sta
## Production tips
- **Use a reverse proxy** (Nginx, Caddy, Traefik) to terminate SSL and serve everything over HTTPS
-- **Update `APP_URL` and `API_URL`** in `.env.taskview` to match your production domain
+- **Update `APP_URL`** in `.env.taskview` and `TASKVIEW_API_URL` on the webapp service to match your production domains
+- **Trim the login page** — set `AUTH_LOGIN_METHODS` in `.env.taskview` to offer only the sign-in methods you actually use (e.g. `AUTH_LOGIN_METHODS="password"`). Google/GitHub/Apple buttons are shown only when the provider is configured.
- **Back up the database** - the `pgdata` volume contains all your data
- **Set `restart: unless-stopped`** on all services so they survive server reboots
- **SMTP setup** - add SMTP variables to `.env.taskview` if you want email features (password recovery, invitations). See [Configuration](/docs/configuration/environment-variables) for details.
diff --git a/docs/2.features/12.ui-customization.md b/docs/2.features/12.ui-customization.md
new file mode 100644
index 0000000..735be93
--- /dev/null
+++ b/docs/2.features/12.ui-customization.md
@@ -0,0 +1,47 @@
+---
+title: UI Customization
+description: Personalize TaskView per user - reorder and hide task fields and analytics blocks, set the first day of week, and pick a default project and view to open right after signing in.
+navigation:
+ icon: i-lucide-sliders-horizontal
+---
+
+TaskView lets every user tune the interface to how they actually work. All settings on this page are personal — they are stored per user on the server and follow you across devices and browsers.
+
+Open **Settings → UI customization** from the user menu.
+
+## Reorder and hide items
+
+Three sections are driven by drag-and-drop lists:
+
+- **Tasks** — the fields shown in the task detail view (note, status, priority, assignees, tags, deadline, sprint, estimate, time tracking, history, …)
+- **Analytics — Indicators** — the KPI tiles on the analytics page
+- **Analytics — Charts** — the charts on the analytics page
+
+For every item you can:
+
+- **Reorder** — drag by the handle on the left
+- **Show / hide** — toggle visibility
+- **Narrow / wide** — for task fields, choose whether the field takes half or the full width of the detail view
+
+All available items are listed here; permission checks still apply at render time, so an enabled item may stay hidden if you lack the permission to see it.
+
+## Others
+
+### First day of week
+
+Sets which day calendars start on. Applies to all date pickers across the app. "Default" follows your locale.
+
+### Default project and view
+
+Normally, after signing in you land on the home screen and navigate to your project and board manually. If you always start in the same place, set it as the default:
+
+- **Default project** — the project TaskView opens right after you sign in (or reopen the app with an active session)
+- **Default view** — which view of that project to open: **Tasks**, **Kanban**, **Graph** or **Sprints**
+
+When a default project is set, a quick-jump button with the project name also appears in the sidebar next to **Inbox** — click it from anywhere to return to your project in the chosen view.
+
+If the default project is deleted or you lose access to it, TaskView falls back to the home screen. Choose "Home screen (default)" to turn the feature off.
+
+## How it is stored
+
+Preferences are saved automatically (no Save button) through the `ui-preferences` API and kept per user account. Resetting the browser or switching devices does not lose them.
diff --git a/docs/4.configuration/1.environment-variables.md b/docs/4.configuration/1.environment-variables.md
index fc4df49..13f9386 100644
--- a/docs/4.configuration/1.environment-variables.md
+++ b/docs/4.configuration/1.environment-variables.md
@@ -27,6 +27,14 @@ These must match your PostgreSQL setup.
| `APP_URL` | Yes | https://app.taskview.tech | Full URL of the web app (e.g. `https://tasks.company.com`). Used for OAuth redirects and email links. |
| `TRUST_PROXY` | No | `false` | Set when running behind a reverse proxy so `X-Forwarded-Proto`/`X-Forwarded-For` are honoured (correct `https` URLs, real client IP). Use the number of proxies in front of the app (`1` for a single Caddy/nginx), or an IP/subnet list (`10.0.0.0/8`, `uniquelocal`). Leave unset for direct access. Avoid `true` (trusts any hop, allows header spoofing). |
+## Web app
+
+Unlike everything else on this page, this variable is set on the **web app container** (`taskview-webapp`), not in `.env.taskview`.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `TASKVIEW_API_URL` | No | - | Pins the API server URL for the web app (e.g. `https://api.company.com`). When set, the "Select server" section disappears from the login page and the app always talks to this API. When unset, users pick the API server on the login page themselves. |
+
## Authentication
| Variable | Required | Default | Description |
@@ -35,6 +43,8 @@ These must match your PostgreSQL setup.
| `ACCESS_LIFE_TIME` | No | `1d` | How long access tokens are valid. Examples: `1h`, `1d`, `7d` |
| `REFRESH_LIFE_TIME` | No | `2d` | How long refresh tokens are valid |
| `JWT_ALG` | No | `HS256` | JWT signing algorithm |
+| `AUTH_LOGIN_METHODS` | No | all enabled | Comma-separated list of login methods to offer: `magic-link`, `password`, `sso`, `social`. Disabled methods disappear from the login page and their API endpoints return 403. The API refuses to start if the list contains a typo or disables every method. |
+| `PASSWORD_CHANGE_CONFIRMATION` | No | `email` | How account password changes are confirmed: `email` — a confirmation code is sent to the user's email (requires SMTP); `password` — the user confirms with their current password (works without SMTP, recommended for installs without a mail server). |
::callout{icon="i-lucide-shield" color="warning"}
Generate a strong JWT secret: `node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"`
@@ -209,6 +219,11 @@ JWT_SIGN="secret"
ACCESS_LIFE_TIME="3d"
REFRESH_LIFE_TIME="9d"
+# Login methods offered on the login page (unset = all enabled)
+#AUTH_LOGIN_METHODS="magic-link,password,sso,social"
+# Password change confirmation: "email" (code by email, needs SMTP) or "password" (no SMTP needed)
+#PASSWORD_CHANGE_CONFIRMATION="email"
+
SMTP_HOST=smtp
SMTP_PORT=587
SMTP_USERNAME=
diff --git a/docs/4.configuration/2.authentication.md b/docs/4.configuration/2.authentication.md
index 9bfe753..d338bd1 100644
--- a/docs/4.configuration/2.authentication.md
+++ b/docs/4.configuration/2.authentication.md
@@ -7,6 +7,21 @@ navigation:
TaskView supports multiple ways to sign in - email/password, email/code, GitHub, Google, and Apple. You can enable whichever methods make sense for your team.
+## Choosing login methods
+
+By default the login page offers every method. Use the `AUTH_LOGIN_METHODS` environment variable to offer only the ones you need:
+
+```env
+# Comma-separated list: magic-link, password, sso, social
+AUTH_LOGIN_METHODS="password,sso"
+```
+
+Disabled methods disappear from the login page and their API endpoints return 403 — the setting is enforced server-side, not just hidden in the UI. Google/GitHub/Apple buttons are additionally shown only when the provider is actually configured, so unconfigured providers never render dead buttons.
+
+::callout{icon="i-lucide-shield" color="warning"}
+The API refuses to start if `AUTH_LOGIN_METHODS` contains an unknown value or disables every method — a broken config can't silently lock everyone out.
+::
+
## Email and password
This is the default method and works out of the box. Users register with an email and password, and log in the same way (email conformation is required).
@@ -14,10 +29,23 @@ This is the default method and works out of the box. Users register with an emai
If you have SMTP configured, users will receive a confirmation email after registration.
Without SMTP, email confirmation is skipped and accounts should be activated manually.
+### Changing your password
+
+Users can set or change their password from **Account settings → Password**. How the change is confirmed depends on the `PASSWORD_CHANGE_CONFIRMATION` environment variable:
+
+- `email` (default) — a confirmation code is sent to the user's email. Requires SMTP.
+- `password` — the user confirms with their current password. No SMTP needed; recommended for installations without a mail server (password login is the only way in there, so every user knows their password).
+
+After a successful change all other sessions are signed out; the current one stays active.
+
### Password recovery
Requires SMTP. Users click "Forgot password" on the login screen, enter their email, and receive a reset link. Without SMTP configured, password recovery is not available - you'll need to reset passwords manually in the database.
+### The default user (self-hosted)
+
+Fresh installations ship a preinstalled user (`user` / `user1!#Q`). That account gets a dedicated **Login and email** card in Account settings to claim it in one step — set your own login, email and password, confirmed by the current password, no SMTP required. See [Installation → Claim the default account](/docs/getting-started/installation#claim-the-default-account).
+
## OAuth providers
TaskView can use external providers for login. This is separate from the integration OAuth (which is for connecting GitHub/GitLab repositories).