Vikunja

https://vikunja.io/docs
Admin
Vikunja is an open-source, self-hostable to-do and task management platform that helps users...
Tokens:105,421
Snippets:1,035
Trust Score:9.9
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run Docker Compose and expected startup log

Source: https://vikunja.io/docs/docker-walkthrough

Run 'sudo docker compose up' to start Vikunja. The expected log output shows the version and the HTTP server starting on port 3456, indicating successful setup.

```bash
sudo docker compose up
```

```log
vikunja_1       | 2024-02-09T14:44:06.990677157+01:00: INFO       ▶ cmd/func29 05d Vikunja version 0.23.0
vikunja_1       | ⇨ http server started on [::]:3456
```

--------------------------------

### Start Vikunja web server with `vikunja web`

Source: https://vikunja.io/docs/cli

Starts Vikunja's web server, serving the API and frontend.

```bash
vikunja web
```

--------------------------------

### Install frontend dependencies with pnpm

Source: https://vikunja.io/docs/build-from-sources

Installs all frontend dependencies using pnpm. Requires pnpm to be installed.

```bash
pnpm install
```

--------------------------------

### Install Vikunja with pacman

Source: https://vikunja.io/docs/installing

Install Vikunja from the pacman repository. After installation, configure Vikunja using the config file in /etc/vikunja/config.yml.

```bash
sudo pacman -Sy vikunja
```

--------------------------------

### Install Vikunja binary and create symlink

Source: https://vikunja.io/docs/installing

Unzips the Vikunja archive, makes the binary executable, and creates a symlink so `vikunja` can be run from anywhere. Installs to `/opt/vikunja` by default.

```bash
mkdir -p /opt/vikunja
unzip <vikunja-zip-file> -d /opt/vikunja
chmod +x /opt/vikunja
sudo ln -s /opt/vikunja/vikunja /usr/bin/vikunja
```

--------------------------------

### Install mage

Source: https://vikunja.io/docs/magefile

Install the mage CLI, which is required to run all Vikunja Mage tasks. Run this before using any of the commands described in the documentation.

```bash
go install github.com/magefile/mage
```

--------------------------------

### Create installation folder and copy binary

Source: https://vikunja.io/docs/installing

Creates /mnt/vikunja, copies the compiled binary from the build directory, and makes it executable.

```shell
mkdir /mnt/vikunja
cp /mnt/GO/code.vikunja.io/api/vikunja /mnt/vikunja
cd /mnt/vikunja
chmod +x /mnt/vikunja
```

--------------------------------

### Enable and start Vikunja systemd service

Source: https://vikunja.io/docs/installing

Enables the Vikunja service to start on boot and starts it immediately.

```bash
sudo systemctl enable vikunja
sudo systemctl start vikunja
```

--------------------------------

### Install Vikunja from Alpine repository

Source: https://vikunja.io/docs/installing

Add the Vikunja Alpine repository, import its signing key, and install Vikunja. Replace 'stable' with 'unstable' to track builds from the main development branch.

```bash
# Add the APK signing key
wget -O /etc/apk/keys/vikunja-apk.rsa.pub https://dl.vikunja.io/repos/apk/vikunja-apk.rsa.pub

# Add the repository
echo "https://dl.vikunja.io/repos/apk/stable/main" >> /etc/apk/repositories

apk update && apk add vikunja
```

--------------------------------

### Install required packages on FreeBSD

Source: https://vikunja.io/docs/installing

Updates the package repository and installs nano, git, gmake, and the mage build tool via go install.

```shell
pkg update && pkg upgrade -y
pkg install nano git go gmake
go install github.com/magefile/mage
```

--------------------------------

### Build the API with Mage

Source: https://vikunja.io/docs/build-from-sources

Builds the API binary in the root of the repo. Requires Go 1.21+ and Mage installed.

```bash
mage build
```

--------------------------------

### Register and implement a listener

Source: https://vikunja.io/docs/events-and-listeners

Example of registering a listener in RegisterListeners() and implementing the listener type. The listener must be registered to be executed; this example increments a task counter when the event fires.

```go
// RegisterListeners registers all event listeners
func RegisterListeners() {
    events.RegisterListener((&ListCreatedEvent{}).Name(), &IncreaseListCounter{})
}

// IncreaseTaskCounter represents a listener
type IncreaseTaskCounter struct {}

// Name defines the name for the IncreaseTaskCounter listener
func (s *IncreaseTaskCounter) Name() string {
    return "task.counter.increase"
}

// Handle is executed when the event IncreaseTaskCounter listens on is fired
func (s *IncreaseTaskCounter) Handle(payload message.Payload) (err error) {
    return keyvalue.IncrBy(metrics.TaskCountKey, 1)
}

```

--------------------------------

### Install Vikunja via direct .deb download

Source: https://vikunja.io/docs/installing

Installs a downloaded .deb package. Installs to /opt/vikunja; configure via /etc/vikunja/config.yml. Default CORS requires setting service.publicurl or disabling cors.enable.

```bash
dpkg -i vikunja.deb
```

--------------------------------

### Install veans standalone binary

Source: https://vikunja.io/docs/veans

Installs the standalone veans binary from the downloads page and places it on the PATH.

```bash
sudo install ./veans /usr/local/bin/
```

--------------------------------

### Install Vikunja via dnf/yum repository (RPM)

Source: https://vikunja.io/docs/installing

Creates the Vikunja yum repository file and installs the package. Replace 'stable' with 'unstable' in baseurl to track development builds.

```bash
sudo tee /etc/yum.repos.d/vikunja.repo <<'EOF'
[vikunja]
name=Vikunja
baseurl=https://dl.vikunja.io/repos/rpm/stable/$basearch
enabled=1
gpgcheck=1
gpgkey=https://dl.vikunja.io/repos/gpg.key
EOF

sudo dnf install vikunja
```

--------------------------------

### Install Vikunja via apt repository (Debian)

Source: https://vikunja.io/docs/installing

Adds the Vikunja apt repository and installs the package. Requires importing the GPG signing key. Replace 'stable' with 'unstable' to track development builds.

```bash
# Import the GPG signing key
curl -fsSL https://dl.vikunja.io/repos/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/vikunja.gpg

# Add the repository
echo "deb [signed-by=/usr/share/keyrings/vikunja.gpg] https://dl.vikunja.io/repos/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/vikunja.list

sudo apt update && sudo apt install vikunja
```

--------------------------------

### Install Vikunja via direct .rpm download

Source: https://vikunja.io/docs/installing

Installs a downloaded .rpm package. Configure via /etc/vikunja/config.yml. Default CORS requires setting service.publicurl or disabling cors.enable.

```bash
rpm -i vikunja.rpm
```

--------------------------------

### Check Vikunja Startup Logs

Source: https://vikunja.io/docs/plugins

Commands to check Vikunja logs for plugin loading status, covering systemd, direct run, and Docker setups.

```bash
# View recent logs
journalctl -u vikunja -n 50
```

```bash
# Or if running directly
tail -f vikunja.log
```

```bash
# Or with docker
docker logs <vikunja container name>
```

--------------------------------

### Create systemd service file for Vikunja

Source: https://vikunja.io/docs/installing

Systemd service unit file to automatically start Vikunja on boot. Save to `/etc/systemd/system/vikunja.service` and adapt paths and dependencies as needed.

```ini
[Unit]
Description=Vikunja
After=syslog.target
After=network.target
# Depending on how you configured Vikunja, you may want to uncomment these:
#Requires=mysql.service
#Requires=mariadb.service
#Requires=postgresql.service
#Requires=redis.service

[Service]
RestartSec=2s
Type=simple
WorkingDirectory=/opt/vikunja
ExecStart=/usr/bin/vikunja
Restart=always
# If you want to bind Vikunja to a port below 1024 uncomment
# the two values below
###
#CapabilityBoundingSet=CAP_NET_BIND_SERVICE
#AmbientCapabilities=CAP_NET_BIND_SERVICE

[Install]
WantedBy=multi-user.target
```

--------------------------------

### GET /api/v1/projects/1/views/5/tasks - Example API request

Source: https://vikunja.io/docs/filters

Example API request showing filters, sort, and order parameters. Use the `filter` query parameter with URL-encoded operators (e.g., `%20%3C` for ` <`, `%20%26%26` for ` &&`).

```text
GET /api/v1/projects/1/views/5/tasks?filter=due_date%20%3C%20now%20%26%26%20done%20%3D%20false&sort_by=priority&order_by=desc
```

--------------------------------

### Build all releases

Source: https://vikunja.io/docs/magefile

Builds binaries for all platforms and zips them with a copy of the templates folder. All built zip files are stored into dist/zips/, binaries into dist/binaries/, and binaries bundled with templates into dist/releases/. Uses xgo, which is installed automatically.

```bash
mage release
```

--------------------------------

### Implement AuthenticatedRouterPlugin and register authenticated routes

Source: https://vikunja.io/docs/plugin-development

Register routes that require user authentication (JWT/API token). Implement AuthenticatedRouterPlugin; routes are prefixed with /api/v1/plugins/. The example shows a GET /user-profile endpoint that fetches the current user and returns JSON.

```go
type AuthenticatedRouterPlugin interface {
    Plugin
    RegisterAuthenticatedRoutes(g *echo.Group)
}

func (p *MyPlugin) RegisterAuthenticatedRoutes(g *echo.Group) {
    // Routes accessible at /api/v1/plugins/user-profile
    g.GET("/user-profile", handleUserProfile)
}

func handleUserProfile(c echo.Context) error {
    // Get database session
    s := db.NewSession()
    defer s.Close()

    // Get authenticated user
    user, err := user.GetCurrentUserFromDB(s, c)
    if err != nil {
        return echo.NewHTTPError(http.StatusUnauthorized, "User not found")
    }

    return c.JSON(http.StatusOK, map[string]interface{}{
        "user_id": user.ID,
        "message": "Hello " + user.Username,
    })
}
```

--------------------------------

### Create dummy index file for frontend

Source: https://vikunja.io/docs/build-from-sources

Creates a dummy index.html if the frontend was not built. Required before building the API if the frontend build was skipped.

```bash
mkdir -p frontend/dist && touch frontend/dist/index.html
```

--------------------------------

### Database connection error log from api container

Source: https://vikunja.io/docs/docker-walkthrough

Error log indicating the api container cannot connect to the database. This often happens on first start with PostgreSQL because the database container takes a few seconds to become ready. The `restart: unless-stopped` option in the docker compose example will automatically restart the api container until the database is ready.

```log
2020/05/23 15:37:59 Config File "config" Not Found in "[/app/vikunja /etc/vikunja /app/vikunja/.config/vikunja]"
2020/05/23 15:37:59 Using default config.
2020-05-23T15:37:59.974435725Z: CRITICAL	▶ migration/Migrate 002 Migration failed: dial tcp 172.19.0.2:3306: connect: connection refused
```

--------------------------------

### Create rc.d startup script for Vikunja

Source: https://vikunja.io/docs/installing

Opens /etc/rc.d/vikunja in nano to create the FreeBSD service script. Paste the provided script content, save, and exit.

```shell
nano /etc/rc.d/vikunja
```

```shell
#!/bin/sh

. /etc/rc.subr

name=vikunja
rcvar=vikunja_enable

command="/mnt/vikunja/${name}"

load_rc_config $name
run_rc_command "$1"
```

--------------------------------

### Build frontend with VIKUNJA_FRONTEND_BASE

Source: https://vikunja.io/docs/running-vikunja-in-a-subdirectory

Run the build command with the VIKUNJA_FRONTEND_BASE environment variable set to the desired subdirectory path. Replace SUBPATH with the actual subdirectory.

```bash
VIKUNJA_FRONTEND_BASE=/SUBPATH/ pnpm run build
```

--------------------------------

### GET /api/v1/filters/{id}

Source: https://vikunja.io/docs/filters

Gets a specific saved filter by ID.

```APIDOC
## GET /api/v1/filters/{id}

### Description
Gets a specific saved filter by ID.

### Method
GET

### Endpoint
/api/v1/filters/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - ID of the saved filter.

### Response
#### Success Response (200)
- **id** (integer) - ID of the saved filter.
- **title** (string) - Title of the saved filter.
- **description** (string) - Description of the saved filter.
- **filters** (object) - Filter configuration.
- **is_favorite** (boolean) - Favorite flag.
- **created** (string) - Creation timestamp.
- **updated** (string) - Last update timestamp.

#### Response Example
{
  "id": 1,
  "title": "My urgent tasks",
  "description": "",
  "filters": {
    "sort_by": ["due_date"],
    "order_by": ["asc"],
    "filter": "priority >= 3 && done = false",
    "filter_include_nulls": false
  },
  "is_favorite": false,
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### Start Vikunja service

Source: https://vikunja.io/docs/installing

Starts the Vikunja service using the service command.

```shell
service vikunja start
```

--------------------------------

### Build OS packages

Source: https://vikunja.io/docs/magefile

Builds .deb, .rpm, and .apk packages to dist/os-packages.

```bash
mage release:packages
```

--------------------------------

### vikunja help [command]

Source: https://vikunja.io/docs/cli

Shows more detailed help about any command.

```bash
vikunja help [command]
```

--------------------------------

### PATCH Partial Update Example

Source: https://vikunja.io/docs/api-v2

Send a JSON Merge Patch to update only specified fields. The example updates the title of label 42.

```http
PATCH /api/v2/labels/42
Content-Type: application/json

{"title": "new title"}
```

--------------------------------

### Build the frontend with pnpm

Source: https://vikunja.io/docs/build-from-sources

Builds the frontend, producing a static JS bundle in the dist/ folder.

```bash
pnpm run build
```

--------------------------------

### Install veans via package manager

Source: https://vikunja.io/docs/veans

Installs veans via the package manager on Debian/Ubuntu, Fedora/RHEL, Arch, or Alpine after adding Vikunja's package repositories.

```bash
sudo apt install veans      # Debian/Ubuntu
sudo dnf install veans      # Fedora/RHEL
sudo pacman -S veans        # Arch
sudo apk add veans          # Alpine
```

--------------------------------

### Initialize veans with a Vikunja server

Source: https://vikunja.io/docs/veans

Initializes veans in a repository that can reach the Vikunja instance. Sets up OAuth 2.0 with PKCE, prompts for a project and Kanban view, creates canonical buckets, creates a bot user, mints an API token, and writes .veans.yml.

```bash
veans init --server https://vikunja.example.com
```

--------------------------------

### Make rc.d script executable and edit rc.conf

Source: https://vikunja.io/docs/installing

Makes the startup script executable and opens /etc/rc.conf to add the vikunja_enable line.

```shell
chmod +x /etc/rc.d/vikunja
nano /etc/rc.conf
```

--------------------------------

### Active Directory minimal configuration (environment variables)

Source: https://vikunja.io/docs/ldap

Environment variable equivalents for the Active Directory minimal configuration.

```bash
VIKUNJA_AUTH_LDAP_ENABLED=true
VIKUNJA_AUTH_LDAP_HOST=ad.your-domain.tld
VIKUNJA_AUTH_LDAP_BASEDN="DC=company,DC=com"
VIKUNJA_AUTH_LDAP_USERFILTER="(&(objectClass=user)(sAMAccountName=%[1]s))"
VIKUNJA_AUTH_LDAP_BINDDN="CN=ServiceAccount,OU=ServiceAccounts,DC=company,DC=com"
VIKUNJA_AUTH_LDAP_BINDPASSWORD="very-secret-password"
VIKUNJA_AUTH_LDAP_ATTRIBUTE_USERNAME=sAMAccountName
```

--------------------------------

### Authentik configuration (environment variables)

Source: https://vikunja.io/docs/ldap

Environment variable equivalents for the Authentik configuration.

```bash
VIKUNJA_AUTH_LDAP_ENABLED=true
VIKUNJA_AUTH_LDAP_PORT=636
VIKUNJA_AUTH_LDAP_VERIFYTLS=false
VIKUNJA_AUTH_LDAP_HOST=auth.your-domain.tld
VIKUNJA_AUTH_LDAP_BASEDN=dc=ldap,dc=your-domain,dc=tld
VIKUNJA_AUTH_LDAP_USERFILTER="(&(objectClass=user)(cn=%s))"
VIKUNJA_AUTH_LDAP_BINDDN="cn=ldap-service-account,ou=users,dc=ldap,dc=your-domain,dc=tld"
VIKUNJA_AUTH_LDAP_BINDPASSWORD="very-secret-password"
```

--------------------------------

### vikunja migrate list

Source: https://vikunja.io/docs/cli

Shows a list with all database migrations.

```bash
vikunja migrate list
```

--------------------------------

### Stricter session lifetime configuration example

Source: https://vikunja.io/docs/security-hardening

Example YAML configuration showing stricter session lifetime values for the service.jwtttlshort, service.jwtttl, and service.jwtttllong keys. The comments indicate the intended meaning of each value.

```yaml
service:
  jwtttlshort: 300   # 5 minutes
  jwtttl: 28800      # 8 hours of inactivity
  jwtttllong: 28800  # "Stay logged in" lasts no longer than a normal session
```

--------------------------------

### Sending a notification with Notify

Source: https://vikunja.io/docs/notifications

Example of sending a notification using the Notify method from the notifications package. It takes a notifiable and a notification as input. This example shows sending an EmailConfirmNotification when a new user registers.

```go
n := &EmailConfirmNotification{
    User:  update.User,
    IsNew: false,
}

err = notifications.Notify(update.User, n)
return

```

--------------------------------

### Implement the Base Plugin Interface

Source: https://vikunja.io/docs/plugin-development

Every plugin must implement this interface. Name() must return a unique identifier, Version() should follow semantic versioning, Init() is called once during startup to register event listeners and initialize resources, and Shutdown() is called during graceful shutdown to clean up resources. Additionally, the plugin must export a NewPlugin() function that returns your plugin instance.

```go
type Plugin interface {
    Name() string    // Unique plugin identifier
    Version() string // Plugin version (semver recommended)
    Init() error     // Called during plugin initialization
    Shutdown() error // Called during graceful shutdown
}
```

--------------------------------

### Register file migrator HTTP routes

Source: https://vikunja.io/docs/migrations

Example of registering HTTP routes for a file migrator using the migrationHandler.FileMigratorWeb helper. The RegisterRoutes(m) method registers routes with the scheme /[MigratorName]/(auth|migrate|status). This example uses the vikunja_file.FileMigrator struct.

```go
vikunjaFileMigrationHandler := &migrationHandler.FileMigratorWeb{
	MigrationStruct: func() migration.FileMigrator {
		return &vikunja_file.FileMigrator{}
	},
}
vikunjaFileMigrationHandler.RegisterRoutes(m)
```
Tokens:
Raw