This PR introduces a partial fix for the CalDAV task listing bug (#753) when handling PROPFIND requests with `Depth: 1`, improving task visibility in the iOS Reminders app.
Notes:
* This might make Thunderbird somewhat usable when interacting with tasks using the `/dav/projects/{id} url`.
* This does not fully resolve the issue where the Reminders app will only display the last project after some time when adding the URL.
This is my first time working with Golang and CalDAV, so I’d really appreciate any feedback or suggestions on the code structure, style, or any improvements I could make.
Co-authored-by: JD <43763092+jdw1023@users.noreply.github.com>
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2717
Reviewed-by: konrad <k@knt.li>
Co-authored-by: jd <jd@noreply.kolaente.dev>
Co-committed-by: jd <jd@noreply.kolaente.dev>
(cherry picked from commit 84dbc5fd84)
This fixes an issue where it would be impossible to update a task in Typesense when the position for a view of it was previously saved as int64. This happened because the field is created per view on demand and its type is automatically inferred from the data saved. Now, when the first value for a particular position field is a float which could as well be an int (for example, 42.0), that field gets created as an int64 instead of float. Subsequent tries to save a float into that field will then fail.
Additionally, errors about this are silently discarded when using bulk insert. That's why the problem was not really debuggable at first.
(cherry picked from commit 50a0674835)
Whenever a task is part of a date filter, it might fall in or out of a filter bucket without anything changing, other than the current time. For example, a filter condition like due_date > now may include different tasks depending on the current time.
For these kinds of tasks to properly show up in the kanban view of a filter, there has to be an entry in the task_buckets table. These entries only got updated when either a task was updated or the filter itself was updated. To account for th changing of time, we also need to check periodically if tasks are now part or not anymore part of that filter.
This change adds a cron task to do precisely that.
We'll have to see if this works resource-wise, but the cron is not the only one doing a bunch of sql queries so it might be fine after all.
Resolves https://community.vikunja.io/t/tasks-in-saved-filter-appear-in-list-view-but-are-not-visible-in-kanban-view/2800
(cherry picked from commit bc52da4029)
This fixes a bug where the full-screen modal would not work on iOS Safari (and only there). It's unclear why this is happening due to a single overflow: visible statement though.
Resolves https://github.com/go-vikunja/vikunja/issues/325
(cherry picked from commit 16d7386975)
This change fixes a bug where the label title in the query string would be replaced to undefined, resulting in an invalid filter. The underlying problem was the resolved filter query string got re-parsed and the id value of the labels were resolved to undefined (and rendered as that string) in the process.
Resolves https://community.vikunja.io/t/filtering-by-label-ux-issues/2393/14
(cherry picked from commit f425d98b4d)
This change allows to specify the task index when creating a task, which will then be checked to avoid duplicates and used. This allows us to calculate the indexes for all tasks beforehand when creating them at once using quick add magic.
The method is not bulletproof, but already fixes a problem where multiple tasks would have the same index when created that way.
Resolves https://community.vikunja.io/t/add-multiple-tasks-at-once/333/16
(cherry picked from commit 55dd7d2981)
Bcrypt allows a maximum of 72 bytes. This is part of the algorithm and not something we could change in Vikunja. The solution here was to restrict the password during registration to a max length of 72 bytes. In the future, this should be changed to hash passwords with sha512 or similar before hashing them with bcrypt. Because they should also be salted in that case and the added complexity during the migration phase, this was not implemented yet.
The change in this commit only improves the error handling to return an input error instead of a server error when the user enters a password > 72 bytes.
Resolves https://vikunja.sentry.io/share/issue/e8e0b64612d84504942feee002ac498a/
(cherry picked from commit 44a43b9f86)
This fixes a bug where the position of a task would not be calculated correctly when the task was moved next to another recently moved task. The problem was caused by the calculation of the new position referring to the old value of the position attribute, because it was not updated in the local store.
Resolves https://community.vikunja.io/t/kanban-cards-in-wrong-order/2731/6
(cherry picked from commit 22e594e253)
Vikunja now uses one recursive CTE and a few optimizations to fetch all subscribers for a task or project. This makes the relevant code easier to maintain and more performant.
(cherry picked from commit 4ff8815fe1)
Before this fix, a project subscription object was added twice to the list of subscriptions for a task when the user did not subscribe to the task directly. This caused the user to receive a comment notification twice for a given task.
This was probably a regression from efde364224.
Resolves https://community.vikunja.io/t/e-mail-notification-twice/2740/18
(cherry picked from commit 2c9becec10)
Previously these store methods created multiple edits on deep objects in the store or edited a deep nested object directly.
This is bad because:
- multiple edits lead to multiple triggers of all the watchers on the project.
- in theory we should listen deep to a project if we use some deep reactive value of a project, if we want deep updates. Because this is easy to forget, it's better to update the project directly. For this the method `setProject` already existed in the store. This is no real overhead because Vue is smart enough to only trigger listeners that use data of the modified state.
By modifying only a copy of the view and submitting the modified result __once__ we can save us a lot of headache.
PS: I'm not sure if there were any visible problems, because Vue is really fast and the reactivity system works quite well. Regardless of this we should try not to modify state unnecessarily.
(cherry picked from commit 1e632397d2)
This fixes a UI issue where if a user had a filter set and marked the task done, it would not disappear, even though the filter does not match the done task anymore.
This fixes a bug where tasks which had their done status changed were not moved in the correct bucket. This affected both frontend and api. The move of the task between buckets is now correctly done in the api and frontend - with a bit of duplicated logic between the two. This could be optimized further in the future.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2610
When creating a related task during the import, migrating would fail because the migration would try to add the task to a bucket before the task was created. This fix changes the order in which that happens to prevent the error.
This fixes a bug where values would not be trimmed before parsing them. That resulted in a value like " 2" being invalid, even though it's a perfectly fine number.
Because the frontend sends the filters for projects and other values with comma-separated spaces like "1, 2, 3", this essentially broke filtering by these values.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2547
Before this fix, creating a project with Typesense enabled would fail with an error because the tasks it fetches as part of that process do not have the task position property in their index. We now fall back to using the db for searching in that case.
In the long run, we should use typesense joins for the task position to make this more efficient.
This somehow weirdly fixes the test. I have no clue why. Regardless it should be better than before, because a button (DropdownItem) should never contain another interactive element (the setBucketLimit input and save button).
The test failed because I replaced a v-if with v-show. I do not know _why_ this made the test fail. When I reproduced the test step by step it worked for me…
display: flow-root creates a new block-formatting context and thus prevents overflowing margin issues created by a last child element that has a margin bottom
BREAKING CHANGE: The bucket id of the task model is now only used internally and will not trigger a change in buckets when updating the task.
This resolves a problem where the task update routine needs to know the view context it is in. Because that's not really what it should be used for, the extra endpoint takes all required parameters and handles the complexity of actually updating the bucket.
This fixes a bug where it was impossible to move a task around between buckets of a saved filter view. In that case, the view of the bucket and the project the task was in would be different, hence the update failed.
When using tsBuildInfoFile composite must be enabled. Because of that we need to change the typecheck command. The command is now the same as the one used by create-vue.
This change fixes a bug where an input query like "labels in test || labels in l" would be replaced with something like "undefinedabels in test || labels in l" or "3abels in test || labels in l" when there was a label starting with "l" - when it should not have touched that.
The matching was changed so that only exact label matches are taken into account when searching for labels.
Now, the above string would be replaced by "labels in 1 || labels in l" (when the label "test" has the id 1).
Maybe resolves https://community.vikunja.io/t/filtering-by-label-ux-issues/2393/8
Originally, it was possible to specify repeating intervals for months or years. This was actually misleading because the interval would be converted to seconds under the hood, causing all kinds of problems with leap years and months with 30 vs 31 days. Because of that, the options for month and year were removed in 7746d39161 to make it clear what these actually meant.
Now, since we do have a repeating mode "Monthly", this commit changes the behaviour to repeat a task monthly when it was specified as "every month", but only that. All other cases were removed from the docs since they are not actually supported.
https://github.com/go-vikunja/vikunja/issues/271
Previously, the bulk api endpoint were explicitly filtered out. This meant that you couldn't use them with api tokens.
This change adds them to their "parent" token types as another option, allowing users to select and use them when creating api tokens.
Resolves https://community.vikunja.io/t/help-with-bulk-api-complete/2461
Also added `Destructuring the 'props' will cause the value to lose reactivity` as a warning to prepare for the removal of the propsDestructure option in vite.
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2396
Reviewed-by: konrad <k@knt.li>
Co-authored-by: Dominik Pschenitschni <mail@celement.de>
Co-committed-by: Dominik Pschenitschni <mail@celement.de>
This change fixes a bug where adding or removing an assignee to a task would not update the index in Typesense, causing filter queries for that assignee to return incorrect data. This was caused by the events being dispatched by the task update process not containing all the data.
Resolves https://github.com/go-vikunja/vikunja/issues/255
This change fixes a bug where Typesense would try to sort by the project view of a saved filter. The view position is not indexed in Typesense, hence filtering fails. Because sorting by position is not a feature in saved filters, I've removed the logic for sorting saved filters with Typesense.
This change fixes a bug where the project view to use for joining was empty, since Typesense only supports 3 sorting parameters. When using more than that, the logic to fetch the view ID parameter would not return the correct parameter, but the logic building the order by statement would. That led to inconsistencies where the task position was included in the order by statement, but the table would not be joined, failing the query.
This change fixes a bug where filter values of views would be transformed in the wrong order, not transformed at all or at the wrong time. Transforming the filters now happens transparently in the background without anything funky happening visible to the user.
Previously, only routes which were coming from crudable entities could be used with an api token because there was no way to assign permissions to them. This change implements a more flexible structure for api permissions under the hood, allowing to add permissions for these routes and making them usable with an api token.
Resolves https://github.com/go-vikunja/vikunja/issues/266
When the demo mode is enabled, people set the language to their own language - which is understandable. However, this is really confusing for other people when they log in and the language is something unexpected.
This change overrides the configured language when saving it while Vikunja is in demo mode.
This fixes a bug where the current number of tasks in a bucket was computed wrong when moving tasks into a bucket with a limit. Sometimes the bug would prevent adding a task to a bucket which seemed to have space left but ultimately failed when moving the task.
Previously, when using the filter query as a search input, it would load the search as requested but the filter query parameter in the url would be empty, which meant the search would not be loaded correctly when reloading (or otherwise newly accessing) the page. We're now persisting the filter and search in the task loading logic, to make sure they are always populated correctly.
This makes task lists (especially big ones) easier to read. I've set a margin so there is a distance between task items which makes them easier to stand out.
I've also changed the visuals of the checked elements (strike through + grey font color) so the unchecked ones stand out more. Note that this currently seems to be a big bugged outside of edit mode as `data-checked` doesn't seem to be updating correctly in this state which seems to be an issue that is already noted for the TipTap editor.
Co-authored-by: Elscrux <nickposer2102@gmail.com>
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2264
Reviewed-by: konrad <k@knt.li>
Co-authored-by: Elscrux <elscrux@gmail.com>
Co-committed-by: Elscrux <elscrux@gmail.com>
This change introduces notifications via mail when a migration fails. It will contain the error message and a hint to post it in the forum when Sentry is disabled, otherwise the error message will be sent directly to sentry and the notification will inform accordingly.
I've tried to balance "this thing failed, go figure it out" with "here is what we know and how you can get help", we'll see how well that approach works.
While attempting to build on OpenBSD without having built the frontend, I ran into the following error:
`frontend/embed.go:21:12: pattern dist: no matching files found`
I saw in the docs to create a directory and touch a file, this resulted in a second error:
`frontend/embed.go:21:12: pattern dist: cannot embed directory dist: contains no embeddable files`
Creating the index.html file inside the new directory allowed me to build Vikunja
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2251
Co-authored-by: Raymi306 <raymi306@gmail.com>
Co-committed-by: Raymi306 <raymi306@gmail.com>
The project grid on the home page with the recently visited projects now contains an even number of projects which makes for a much nicer grid (because it's now uniform).
When the tasks were migrated from belonging directly to a bucket to only belonging to a view, I forgot to add the view in that migration, resulting in task buckets where the view was 0. These entries were not deleted when a task was moved between buckets, but the new task bucket relation nevertheless inserted. This resulted in tasks showing up multiple times on the kanban board.
This change adds a new migration which adds the correct project view id (as derived from the bucket) and fixes the old migration as well.
Resolves https://community.vikunja.io/t/no-longer-able-to-properly-move-tasks-between-kanban-columns/2175
Previously, in a filter like "due_date = now/d", the / was parsed as the beginning of a comment, but as it did not contain the full value, this is an invalid comment, resulting in an error message.
Resolves https://community.vikunja.io/t/filter-setting-s/1791/12
Before this change, the filter button on the top right was positioned using absolute positioning and plenty of tricks, which were brittle and not really maintainable. Now, the buttons are positioned using flexbox, which should make this a lot more maintainable.
Previously, the actual filter was kept as-is when sending it to the api, essentially creating an invalid filter. This change fixes this, transforming the filter before saving and after loading.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2233
When a new project was created, it contained all details already. This led to duplicated views and overridden attributes in the response.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2242
This PR decouples views from projects. On the surface, everything stays the same - by default, there are the same views as right now in main - List, Gantt, Table, Kanban. With this feature, it is possible to modify these or create new ones. That means you can remove views you never need or create multiple ones if you need different configurations.
Each view can have an optional filter to change what you see in the frontend on that view. For kanban, you can either set it to "manual" mode, where you can create buckets and move tasks around, or "filter" mode, where each bucket is the result of a filter (and you cannot move them around).
All positions and buckets are now tied to the view, not the project. This means you can (finally!) have views for saved filters.
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2217
BREAKING CHANGE: the position of tasks now can't be updated anymore via the task update endpoint. Instead, there is a new endpoint which takes the project view into account as well.
BREAKING CHANGE: tasks in their bucket are now only retrievable via their view. The /project/:id/buckets endpoint now only returns the buckets for that project, which is more in line with the other endpoints
It looks like links are opened twice, when the openOnClick option is enabled. That means they will get opened twice when clicking on them. Disabling that option will not fire the click handler and only rely on browser functionality to open links.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2155
Flatpickr only returns a change event when the value in the input it's referring to changes. That means it will usually only trigger when the focus is moved out of the input field. This is fine most of the time. However, since we're displaying flatpickr in a popup, the whole html dom instance might get destroyed, before the change event had a chance to fire. In that case, it would not update the date value. To fix this, we're now listening on every change and bubble them up as soon as they happen.
Resolves https://community.vikunja.io/t/due-date-confirm-button-not-working/2104
This fixes a bug where the project title would not be replaced correctly in cases where the project title contained parts of the word "project".
Resolves https://kolaente.dev/vikunja/vikunja/issues/2194
This PR adds reactions for tasks and comments, similar to what you can do on Gitea, GitHub, Slack and plenty of other tools.
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2196
Co-authored-by: kolaente <k@knt.li>
Co-committed-by: kolaente <k@knt.li>
Previously, when creating a filter query with the 'in' operator and multiple values, autocompletion and highlighting was not available. This change now implements a split for each value, seperated by a comma.
This PR fixes an issue discussed in #2152. Before this PR, the user who triggered team creation automatically got the admin flag set for this group, which makes perfect sense for the normal UI workflow. OIDC managed teams cannot be edited in Vikunja, and they're created automatically by the first user logging in having this team assigned. This PR therefore makes sure that OIDC managed team members do not receive the admin flag.
Co-authored-by: Daniel Herrmann <daniel.herrmann1@gmail.com>
Reviewed-on: https://kolaente.dev/vikunja/vikunja/pulls/2161
Reviewed-by: konrad <k@knt.li>
Co-authored-by: waza-ari <daniel.herrmann@makerspace-darmstadt.de>
Co-committed-by: waza-ari <daniel.herrmann@makerspace-darmstadt.de>
Testing this locally resulted in improved response times from ~50ms to ~20ms when creating a project. It looks like even though the code running these sql queries uses different go routines, they affect each other (caused by IO or context switching?)
This change ensures already loaded projects are passed down when fetching their subscription instead of re-loading each project with a single sql statement. When loading all projects, this meant all projects were loaded twice, which was highly inefficient. This roughly added 25ms to each request, assuming the per page limit was maxed out at 50 projects.
Empirical testing shows this change reduces load times by ~20ms. Because the request is already pretty fast, this is ~30% of the overall request time, making the loading of projects now even faster
Since Vikunja's docker image is now based on the scratch image, the root ca certificates are not included by default anymore. This meant Vikunja could not check if the certificate presented by a remote host was valid, thus failing the connection. This meant it was impossible to use features communicating with external hosts such as webhooks, openid auth or gravatar.
Before this change, applying a filter and then scrolling a bucket would not use that filter when lazy loading the tasks in that bucket. That resulted in all tasks being loaded, regardless if the filter applied to them.
This change modifies the docker image so that it uses the scratch image instead of alpine. This is possible because the Vikunja binary is now entirely statically compiled, wich no dependencies on any system c libraries.
This also changes the default path for the sqlite file in the docker image (breaking). When using sqlite in docker, the VIKUNJA_DATABASE_PATH config variable or the file mount must be changed to prevent data loss.
This explicitly adds download and upload of task attachments. Because these are not handled with the usual CRUDables, they were not picked up automatically.
Resolves https://github.com/go-vikunja/vikunja/issues/112
Before this fix, clicking on a task list item with the same name as another one, both would get marked as done. This was due to the mechanism which walks the dom tree to look for the node to update used its content for comparison. To prevent this, this fix first added unique ids to all task list items and then compared the nodes based on their id instead of the content.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2091
This change fixes a bug where Vikunja would not correctly check if a migration was already running. That meant it was not possible for users who had never before migrated anything to start a migration, because Vikunja assumed they already had a migration running for them.
This state was neither properly reflected in the frontend, which is now fixed as well.
Previously, Vikunja would allow imports from any version which then caused problems since the table structure might have changed between releases. This change now checks if the current version is the same as the one the dump was created on.
This fixes a problem where Vikunja would sometimes return the html for the frontend when accessing an api route for a nonexistent ressource, because the static handler was the next best.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2110
With this change, the project's collapsed open/closed state in the navigation survives a browser reload. Previously, all state would be lost after reloading.
Resolves https://kolaente.dev/vikunja/vikunja/issues/2067
When adding a new task relation, the task search input would previously show all tasks in a seemingly random order, including done tasks. Usually, you don't care about these done tasks when adding relations. This change modifies the sort order so that done tasks show up last in the search results.
It looks like Drone executes all commands with sh, even if the default shell of the container is something else. Because sh does not have support for whitespaces in string extrapolation, the rename command would fail. This change always specifies bash as the shell.
Username and password are validated in the api for length and whitespaces. Previously, the api would tell the user "hey you got it wrong" but the error was not reflected properly in the UI. This change implements a client-side validation which mirrors the one from the api, allowing instant validation and better error UX.
If Vikunja is useful to you, please consider [buying me a coffee](https://www.buymeacoffee.com/kolaente), [sponsoring me on GitHub](https://github.com/sponsors/kolaente) or buying [a sticker pack](https://vikunja.cloud/stickers).
I'm also offering [a hosted version of Vikunja](https://vikunja.cloud/) if you want a hassle-free solution for yourself or your team.
# Table of contents
* [Security Reports](#security-reports)
@@ -26,7 +29,7 @@ If you find any security-related issues you don't want to disclose publicly, ple
## Features
See [the features page](https://vikunja.io/features/) on our website for a more exaustive list or
See [the features page](https://vikunja.io/features/) on our website for a more exhaustive list or
try it on [try.vikunja.io](https://try.vikunja.io)!
# Database type to use. Supported types are mysql, postgres and sqlite.
# Database type to use. Supported values are mysql, postgres and sqlite. Vikunja is able to run with MySQL 8.0+, Mariadb 10.2+, PostgreSQL 12+, and sqlite.
type: "sqlite"
# Database user which is used to connect to the database.
user: "vikunja"
@@ -109,7 +112,7 @@ database:
typesense:
# Whether to enable the Typesense integration. If true, all tasks will be synced to the configured Typesense
# instance and all search and filtering will run through Typesense instead of only through the database.
# Typesense allows fast fulltext search including fuzzy matching support. It may return different results than
# Typesense allows fast fulltext search including fuzzy matching support. It may return different results than
# what you'd get with a database-only search.
enabled: false
# The url to the Typesense instance you want to use. Can be hosted locally or in Typesense Cloud as long
@@ -153,7 +156,7 @@ mailer:
username: "user"
# SMTP password
password: ""
# Wether to skip verification of the tls certificate on the server
# Whether to skip verification of the tls certificate on the server
skiptlsverify: false
# The default from address when sending emails
fromemail: "mail@vikunja"
@@ -161,7 +164,7 @@ mailer:
queuelength: 100
# The timeout in seconds after which the current open connection to the mailserver will be closed.
queuetimeout: 30
# By default, vikunja will try to connect with starttls, use this option to force it to use ssl.
# By default, Vikunja will try to connect with starttls, use this option to force it to use ssl.
forcessl: false
log:
@@ -203,7 +206,7 @@ ratelimit:
# Possible values are "keyvalue", "memory" or "redis".
# When choosing "keyvalue" this setting follows the one configured in the "keyvalue" section.
store: keyvalue
# The number of requests a user can make from the same IP to all unauthenticated routes (login, register,
# The number of requests a user can make from the same IP to all unauthenticated routes (login, register,
# password confirmation, email verification, password reset request) per minute. This limit cannot be disabled.
# You should only change this if you know what you're doing.
noauthlimit: 10
@@ -220,27 +223,28 @@ migration:
# Wheter to enable the todoist migrator or not
enable: false
# The client id, required for making requests to the todoist api
# You need to register your vikunja instance at https://developer.todoist.com/appconsole.html to get this
# You need to register your Vikunja instance at https://developer.todoist.com/appconsole.html to get this
clientid:
# The client secret, also required for making requests to the todoist api
clientsecret:
# The url where clients are redirected after they authorized Vikunja to access their todoist items.
# This needs to match the url you entered when registering your Vikunja instance at todoist.
# This is usually the frontend url where the frontend then makes a request to /migration/todoist/migrate
# The url where clients are redirected after they authorized Vikunja to access their Todoist items.
# In Todoist, this is called `OAuth redirect URL` and it needs to match the url you entered when registering
# your Vikunja instance at the Todoist developer console.
# When using the official Vikunja frontend, set this to <service.publicurl>/migrate/todoist.
# Otherwise, set this to an url which then makes a request to /api/v1/migration/todoist/migrate
# with the code obtained from the todoist api.
# Note that the vikunja frontend expects this to be /migrate/todoist
redirecturl: <frontend url>/migrate/todoist
redirecturl: <service.publicurl>/migrate/todoist
trello:
# Whether to enable the trello migrator or not
enable: false
# The client id, required for making requests to the trello api
# You need to register your vikunja instance at https://trello.com/app-key (log in before you visit that link) to get this
# You need to register your Vikunja instance at https://trello.com/app-key (log in before you visit that link) to get this
key:
# The url where clients are redirected after they authorized Vikunja to access their trello cards.
# This needs to match the url you entered when registering your Vikunja instance at trello.
# This is usually the frontend url where the frontend then makes a request to /migration/trello/migrate
# with the code obtained from the trello api.
# Note that the vikunja frontend expects this to end on /migrate/trello.
# Note that the Vikunja frontend expects this to end on /migrate/trello.
redirecturl: <frontend url>/migrate/trello
microsofttodo:
# Wheter to enable the microsoft todo migrator or not
@@ -255,7 +259,7 @@ migration:
# This needs to match the url you entered when registering your Vikunja instance at microsoft.
# This is usually the frontend url where the frontend then makes a request to /migration/microsoft-todo/migrate
# with the code obtained from the microsoft graph api.
# Note that the vikunja frontend expects this to be /migrate/microsoft-todo
# Note that the Vikunja frontend expects this to be /migrate/microsoft-todo
# OpenID configuration will allow users to authenticate through a third-party OpenID Connect compatible provider.<br/>
# The provider needs to support the `openid`, `profile` and `email` scopes.<br/>
# **Note:** Some openid providers (like gitlab) only make the email of the user available through openid claims if they have set it to be publicly visible.
# **Note:** Some openid providers (like Gitlab) only make the email of the user available through OpenID if they have set it to be publicly visible.
# If the email is not public in those cases, authenticating will fail.
# **Note 2:** The frontend expects to be redirected after authentication by the third party
# to <frontend-url>/auth/openid/<auth key>. Please make sure to configure the redirect url in your third party
# auth service accordingly if you're using the default vikunja frontend.
# The frontend will automatically provide the api with the redirect url, composed from the current url where it's hosted.
# If you want to use the desktop client with openid, make sure to allow redirects to `127.0.0.1`.
# +**Note 2:** The frontend expects the third party to redirect the user <frontend-url>/auth/openid/<auth key> after authentication. Please make sure to configure the redirect url in your third party auth service accordingly if you're using the default Vikunja frontend.
# The frontend will automatically provide the API with the redirect url, composed from the current url where it's hosted.
# If you want to use the desktop client with OpenID, make sure to allow redirects to `127.0.0.1`.
# Take a look at the [default config file](https://kolaente.dev/vikunja/vikunja/src/branch/main/config.yml.sample) for more information about how to configure openid authentication.
openid:
# Enable or disable OpenID Connect authentication
@@ -325,6 +327,10 @@ auth:
clientid:
# The client secret used to authenticate Vikunja at the OpenID Connect provider.
clientsecret:
# The scope necessary to use oidc.
# If you want to use the Feature to create and assign to Vikunja teams via oidc, you have to add the custom "vikunja_scope" and check [openid.md](https://vikunja.io/docs/openid/).
# e.g. scope: openid email profile vikunja_scope
scope: openid email profile
# Prometheus metrics endpoint
metrics:
@@ -363,8 +369,8 @@ defaultsettings:
webhooks:
# Whether to enable support for webhooks
enabled: true
# The timout in seconds until a webhook request fails when no response has been received.
timoutseconds: 30
# The timeout in seconds until a webhook request fails when no response has been received.
timeoutseconds: 30
# The URL of [a mole instance](https://github.com/frain-dev/mole) to use to proxy outgoing webhook requests. You should use this and configure appropriately if you're not the only one using your Vikunja instance. More info about why: https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication. Must be used in combination with `webhooks.password` (see below).
proxyurl:
# The proxy password to use when authenticating against the proxy.
Cron jobs are tasks which run on a predefined schedule.
Vikunja uses these through a light wrapper package around the excellent [github.com/robfig/cron](https://github.com/robfig/cron) package.
The package exposes a `cron.Schedule` method with two arguments: The first one to define the schedule when the cron task should run, and the second one with the actual function to run at the schedule. You would then create a new function to register your the actual cron task in your package.
A basic function to register a cron task looks like this:
```go
funcRegisterSomeCronTask(){
err:=cron.Schedule("0 * * * *",func(){
// Do something every hour
}
}
```
Call the register method in the `FullInit()` method of the `init` package to actually register it.
## Schedule Syntax
The cron syntax uses the same on you may know from unix systems.
It is described in detail [here](https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format).
Vikunja uses [xorm](https://xorm.io/) as an abstraction layer to handle the database connection.
Please refer to [their](https://xorm.io/docs/) documentation on how to exactly use it.
{{< table_of_contents >}}
## Using the database
When using the common web handlers, you get an `xorm.Session` to do database manipulations.
In other packages, use the `db.NewSession()` method to get a new database session.
## Adding new database tables
To add a new table to the database, create the struct and [add a migration for it]({{< ref "db-migrations.md" >}}).
To learn more about how to configure your struct to create "good" tables, refer to [the xorm documentaion](https://xorm.io/docs/).
In most cases you will also need to implement the `TableName() string` method on the new struct to make sure the table name matches the rest of the tables - plural.
## Adding data to test fixtures
Adding data for test fixtures can be done via `yaml` files in `pkg/models/fixtures`.
The name of the yaml file should match the table name in the database.
Adding values to it is done via array definition inside it.
**Note**: Table and column names need to be in snake_case as that's what is used internally in the database and for mapping values from the database to xorm so your structs can use it.
To contribute to Vikunja, fork the project and work on the main branch.
Once you feel like your changes are ready, open a PR in the respective repo [on our Gitea instance](https://kolaente.dev/vikunja).
We cannot accept PRs on mirror sites.
A maintainer will take a look and give you feedback. Once everyone is happy, the PR gets merged and released.
If you plan to do a bigger change, it is better to open an issue for discussion first.
The main repo is [`vikunja/vikunja`](https://kolaente.dev/vikunja/vikunja), it contains all code for the api, frontend and desktop applications.
## API
You'll need at least Go 1.21 to build Vikunja's api.
A lot of developing tasks are automated using a Magefile, so make sure to [take a look at it]({{< ref "mage.md">}}).
Make sure to check the other doc articles for specific development tasks like [testing]({{< ref "test.md">}}),
[database migrations]({{< ref "db-migrations.md" >}}) and the [project structure]({{< ref "structure.md" >}}).
## Frontend requirements
The code for the frontend is located in the `frontend` sub folder of the main repo.
More instructions can be found in the repo's README.
You need to have [pnpm](https://pnpm.io/) and Node.JS in version 20 or higher installed.
## Pull Requests
All Pull Requests must be made [on our Gitea instance](https://kolaente.dev/vikunja).
We cannot accept PRs on mirror sites.
Please try to make your pull request easy to review.
For that, please read the [*Best Practices for Faster Reviews*](https://github.com/kubernetes/community/blob/261cb0fd089b64002c91e8eddceebf032462ccd6/contributors/guide/pull-requests.md#best-practices-for-faster-reviews) guide.
It has lots of useful tips for any project you may want to contribute to.
Some of the key points:
- Make small pull requests.
The smaller, the faster to review and the more likely it will be merged soon.
- Don't make changes unrelated to your PR.
Maybe there are typos on some comments, maybe refactoring would be welcome on a function…
but if that is not related to your PR, please make *another* PR for that.
- Split big pull requests into multiple small ones.
An incremental change will be faster to review than a huge PR.
- Allow edits by maintainers. This way, the maintainers will take care of merging the PR later on instead of you.
### PR title and summary
In the PR title, describe the problem you are fixing, not how you are fixing it.
Use the first comment as a summary of your PR.
In the PR summary, you can describe exactly how you are fixing this problem.
Keep this summary up-to-date as the PR evolves.
If your PR changes the UI, you must add **after** screenshots in the PR summary.
If your PR closes an issue, you must note that in a way that both GitHub and Gitea understand, i.e. by appending a paragraph like
```text
Fixes/Closes/Resolves #<ISSUE_NR_X>.
Fixes/Closes/Resolves #<ISSUE_NR_Y>.
```
to your summary.
Each issue that will be closed must stand on a separate line.
If your PR is related to a discussion in the forum, you must add a link to the forum discussion.
### Git flow
The `main` branch is the latest and bleeding edge branch with all changes. Unstable releases are automatically created from this branch.
New Pull-Requests should be made against the `main` branch.
A release gets tagged from the main branch with the version name as tag name.
Backports and point-releases should go to a `release/version` branch, based on the tag they are building on top of.
## Conventional Commits
We're using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) because they simplify generating release notes a lot.
It is not required to use them when creating a PR, but appreciated.
As you can see, the current task and doer are injected into it.
### Special Events
#### `BootedEvent`
Once Vikunja is fully initialized, right before the api web server is started, this event is fired.
## Listeners
A listener is a piece of code that gets executed asynchronously when an event is dispatched.
A single event can have multiple listeners who are independent of each other.
### Definition
All listeners must implement this interface:
```go
// Listener represents something that listens to events
typeListenerinterface{
Handle(msg*message.Message)error
Name()string
}
```
The `Handle` method is executed when the event this listener listens on is dispatched.
* As the single parameter, it gets the payload of the event, which is the event struct when it was dispatched decoded as json object and passed as a slice of bytes.
To use it you'll need to unmarshal it. Unfortunately there's no way to pass an already populated event object to the function because we would not know what type it has when parsing it.
* If the handler returns an error, the listener is retried 5 times, with an exponential back-off period in between retries.
If it still fails after the fifth retry, the event is nack'd and it's up to the event dispatcher to resend it.
You can learn more about this mechanism in the [watermill documentation](https://watermill.io/docs/middlewares/#retry).
The `Name` method needs to return a unique listener name for this listener.
It should follow the same convention as event names, see above.
### Creating a New Listener
The easiest way to create a new listener for an event is with mage:
Vikunja uses [Mage](https://magefile.org/) to script common development tasks and even releasing.
Mage is a pure go solution which allows for greater flexibility and things like better parallelization.
This document explains what tasks are available and what they do.
{{< table_of_contents >}}
## Installation
To use mage, you'll need to install the mage cli.
To install it, run the following command:
```
go install github.com/magefile/mage
```
## Categories
There are multiple categories of subcommands in the magefile:
*`build`: Contains commands to build a single binary
*`check`: Contains commands to statically check the source code
*`release`: Contains commands to release Vikunja with everything that's required
*`test`: Contains commands to run all kinds of tests
*`dev`: Contains commands to run development tasks
*`misc`: Commands which do not belong in either of the other categories
## CI
These tasks are automatically run in our CI every time someone pushes to main or you update a pull request:
*`mage check:lint`
*`mage check:fmt`
*`mage check:ineffassign`
*`mage check:misspell`
*`mage check:goconst`
*`mage build:generate`
*`mage build:build`
## Build
### Build Vikunja
```
mage build:build
```
or
```
mage build
```
Builds a `vikunja`-binary in the root directory of the repo for the platform it is run on.
### clean
```
mage build:clean
```
Cleans all build and executable files
## Check
All check sub-commands exit with a status code of 1 if the check fails.
Various code-checks are available:
*`mage check:all`: Runs fmt-check, lint, got-swag, misspell-check, ineffasign-check, gocyclo-check, static-check, gosec-check, goconst-check all in parallel
*`mage check:fmt`: Checks if the code is properly formatted with go fmt
*`mage check:go-sec`: Checks the source code for potential security issues by scanning the Go AST using the [gosec tool](https://github.com/securego/gosec)
*`mage check:goconst`: Checks for repeated strings that could be replaced by a constant using [goconst](https://github.com/jgautheron/goconst/)
*`mage check:gocyclo`: Checks for the cyclomatic complexity of the source code using [gocyclo](https://github.com/fzipp/gocyclo)
*`mage check:got-swag`: Checks if the swagger docs need to be re-generated from the code annotations
*`mage check:ineffassign`: Checks the source code for ineffectual assigns using [ineffassign](https://github.com/gordonklaus/ineffassign)
*`mage check:lint`: Runs golint on all packages
*`mage check:misspell`: Checks the source code for misspellings
*`mage check:static`: Statically analyzes the source code about a range of different problems using [staticcheck](https://staticcheck.io/docs/)
## Release
### Build Releases
```
mage release
```
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 are stored in `dist/binaries/`,
binaries bundled with `templates` are stored in `dist/releases/`.
All cross-platform binaries built using this series of commands are built with the help of
[xgo](https://github.com/techknowlogick/xgo). The mage command will automatically install the
binary to be able to use it.
`mage release:release` is a shortcut to execute `mage release:dirs release:windows release:linux release:darwin release:copy release:check release:os-package release:zip`.
*`mage release:dirs` creates all directories needed
*`mage release:windows`/`release:linux`/`release:darwin` execute xgo to build for their respective platforms
*`mage release:copy` bundles binaries with a copy of the `LICENSE` and sample config files to then be zipped
*`mage release:check` creates sha256 checksums for each binary which will be included in the zip file
*`mage release:os-package` bundles a binary with the `sha256` checksum file, a sample `config.yml` and a copy of the license in a folder for each architecture
*`mage release:compress` compresses all build binaries with `upx` to save space
*`mage release:zip` packages a zip file for the files created by `release:os-package`
### Build os packages
```
mage release:packages
```
Will build `.deb`, `.rpm` and `.apk` packages to `dist/os-packages`.
### Make a debian repo
```
mage release:reprepro
```
Takes an already built debian package and creates a debian repo structure around it.
Used to be run inside a [docker container](https://git.kolaente.de/konrad/reprepro-docker) in the CI process when releasing.
## Test
### unit
```
mage test:unit
```
Runs all tests except integration tests.
### coverage
```
mage test:coverage
```
Runs all tests except integration tests and generates a `coverage.html` file to inspect the code coverage.
### integration
```
mage test:integration
```
Runs all integration tests.
## Dev
### Create a new migration
```
mage dev:create-migration
```
Creates a new migration with the current date.
Will ask for the name of the struct you want to create a migration for.
See also [migration docs]({{< ref "mage.md" >}}).
## Misc
### Format the code
```
mage fmt
```
Formats all source code using `go fmt`.
### Generate swagger definitions from code comments
```
mage do-the-swag
```
Generates swagger definitions from the comment annotations in the code.
Metrics work by exposing a `/metrics` endpoint which can then be accessed by prometheus.
To keep the load on the database minimal, metrics are stored and updated in redis.
The `metrics` package provides several functions to create and update metrics.
{{< table_of_contents >}}
## Exposing New Metrics
First, define a `const` with the metric key in redis. This is done in `pkg/metrics/metrics.go`.
To expose a new metric, you need to register it in the `init` function inside of the `metrics` package like so:
```go
// Register total user count metric
promauto.NewGaugeFunc(prometheus.GaugeOpts{
Name: "vikunja_team_count", // The key of the metric. Must be unique.
Help: "The total number of teams on this instance", // A description about the metric itself.
}, func() float64 {
count, _ := GetCount(TeamCountKey) // TeamCountKey is the const we defined earlier.
return float64(count)
})
```
Then you'll need to set the metrics initial value on every startup of Vikunja.
This is done in `pkg/routes/routes.go` to avoid cyclic imports.
If metrics are enabled, it checks if a redis connection is available and then sets the initial values.
A convenience function is available if the metric is based on a database struct.
Because metrics are stored in redis, you are responsible to increase or decrease these based on criteria you define.
To do this, use `metrics.UpdateCount(value, key)` where `value` is the amount you want to change it (you can pass negative values to decrease it) and `key` it the redis key used to define the metric.
## Using it
A Prometheus config with a Grafana template is available at [our git repo](https://git.kolaente.de/vikunja/monitoring).
It is possible to migrate data from other to-do services to Vikunja.
To make this easier, we have put together a few helpers which are documented on this page.
In general, each migrator implements a migrator interface which is then called from a client.
The interface makes it possible to use helper methods which handle http and focus only on the implementation of the migrator itself.
There are two ways of migrating data from another service:
1. Through the auth-based flow where the user gives you access to their data at the third-party service through an oauth flow. You can then call the service's api on behalf of your user to get all the data. The Todoist, Trello and Microsoft To-Do Migrators use this pattern.
2. A file migration where the user uploads a file obtained from some third-party service. In your migrator, you need to parse the file and create the projects, tasks etc. The Vikunja File Import uses this pattern.
To differentiate the two, there are two different interfaces you must implement.
{{< table_of_contents >}}
## Structure
All migrator implementations live in their own package in `pkg/modules/migration/<name-of-the-service>`.
When creating a new migrator, you should place all related code inside that module.
## Migrator Interface
The migrator interface is defined as follows:
```go
// Migrator is the basic migrator interface which is shared among all migrators
type Migrator interface {
// Name holds the name of the migration.
// This is used to show the name to users and to keep track of users who already migrated.
Name() string
// Migrate is the interface used to migrate a user's tasks from another platform to Vikunja.
// The user object is the user who's tasks will be migrated.
Migrate(user *models.User) error
// AuthURL returns a url for clients to authenticate against.
// The use case for this are Oauth flows, where the server token should remain hidden and not
// known to the frontend.
AuthURL() string
}
```
## File Migrator Interface
```go
// FileMigrator handles importing Vikunja data from a file. The implementation of it determines the format.
type FileMigrator interface {
// Name holds the name of the migration.
// This is used to show the name to users and to keep track of users who already migrated.
Name() string
// Migrate is the interface used to migrate a user's tasks, projects and other things from a file to Vikunja.
// The user object is the user who's tasks will be migrated.
Once your migrator implements the migration interface, it becomes possible to use the helper http handlers.
Their usage is very similar to the [general web handler](https://kolaente.dev/vikunja/web#user-content-defining-routes-using-the-standard-web-handler):
The `RegisterRoutes(m)` method registers all routes with the scheme `/[MigratorName]/(auth|migrate|status)` for the
You should also document the routes with [swagger annotations]({{< ref "swagger-docs.md" >}}).
## Insertion helper method
There is a method available in the `migration` package which takes a fully nested Vikunja structure and creates it with all relations.
This means you start by adding a project, then add projects inside that project, then tasks in the lists and so on.
In general, it is reccommended to have one root project with all projects of the other service as child projects.
The root structure must be present as `[]*models.ProjectWithTasksAndBuckets`. It allows to represent all of Vikunja's hierarchy as a single data structure.
If your migrator is an oauth-based one, you should add at least an option to enable or disable it.
Chances are, you'll need some more options for things like client ID and secret (if the other service uses oAuth as an authentication flow).
The easiest way to implement an on/off switch is to check whether your migration service is enabled or not when registering the routes, and then simply don't registering the routes in case it is disabled.
File based migrators can always be enabled.
### Making the migrator public in `/info`
You should make your migrator available in the `/info` endpoint so that frontends can display options to enable them or not.
To do this, add an entry to the `AvailableMigrators` field in `pkg/routes/api/v1/info.go`.
Vikunja provides a simple abstraction to send notifications per mail and in the database.
{{< table_of_contents >}}
## Definition
Each notification has to implement this interface:
```go
type Notification interface {
ToMail() *Mail
ToDB() interface{}
Name() string
}
```
Both functions return the formatted messages for mail and database.
A notification will only be sent or recorded for those of the two methods which don't return `nil`.
For example, if your notification should not be recorded in the database but only sent out per mail, it is enough to let the `ToDB` function return `nil`.
### Mail notifications
A list of chainable functions is available to compose a mail:
```go
mail := NewMail().
// The optional sender of the mail message.
From("test@example.com").
// The optional recipient of the mail message. Uses the mail address of the notifiable if omitted.
To("test@otherdomain.com").
// The subject of the mail to send.
Subject("Testmail").
// The greeting, or "intro" line of the mail.
Greeting("Hi there,").
// A line of text
Line("This is a line of text").
// An action can contain a title and a url. It gets rendered as a big button in the mail.
// Note that you can have only one action per mail.
// All lines added before an action will appear in the mail before the button, all lines
// added afterwards will appear after it.
Action("The Action", "https://example.com").
// Another line of text.
Line("This should be an outro line").
```
If not provided, the `from` field of the mail contains the value configured in [`mailer.fromemail`](https://vikunja.io/docs/config-options/#fromemail).
### Database notifications
All data returned from the `ToDB()` method is serialized to json and saved into the database, along with the id of the notifiable, the name of the notification and a time stamp.
If you don't use the database notification, the `Name()` function can return an empty string.
## Creating a new notification
The easiest way to generate a mail is by using the `mage dev:make-notification` command.
It takes the name of the notification and the package where the notification will be created.
## Notifiables
Notifiables can receive a notification.
A notifiable is defined with this interface:
```go
type Notifiable interface {
// Should return the email address this notifiable has.
RouteForMail() string
// Should return the id of the notifiable entity
RouteForDB() int64
}
```
The `User` type from the `user` package implements this interface.
## Sending a notification
Sending a notification is done with the `Notify` method from the `notifications` package.
It takes a notifiable and a notification as input.
For example, the email confirm notification when a new user registers is sent like this:
```go
n := &EmailConfirmNotification{
User: update.User,
IsNew: false,
}
err = notifications.Notify(update.User, n)
return
```
## Testing
The `mail` package provides a `Fake()` method which you should call in the `MainTest` functions of your package.
If it was called, no mails are being sent and you can instead assert they have been sent with the `AssertSent` method.
When testing, you should call the `notifications.Fake()` method in the `TestMain` function of the package you want to test.
This prevents any notifications from being sent and lets you assert a notifications has been sent like this:
The root directory is where [the config file]({{< ref "../setup/config.md">}}), [Magefile]({{< ref "mage.md">}}), license, drone config,
application entry point (`main.go`) and so on are located.
## pkg
This is where most of the magic happens. Most packages with actual code are located in this folder.
### caldav
This folder holds a simple caldav implementation which is responsible for the caldav feature.
### cmd
This package contains all cli-related files and functions.
To learn more about how to add a new command, see [the cli docs]({{< ref "cli.md">}}).
To learn more about how to use this cli, see [the cli usage docs]({{< ref "../usage/cli.md">}}).
### config
This package configures handling of Vikunja's runtime configuration.
It sets default values and sets up viper and tells it where to look for config files, how to interpret which env variables
for config etc.
See also the [docs about adding a new configuration parameter]({{< ref "config.md" >}}).
### cron
See [how to add a cron task]({{< ref "cron.md" >}}).
### db
This package contains the db connection handling and db fixtures for testing.
Each other package gets its db connection object from this package.
### files
This package is responsible for all file-related things.
This means it handles saving and retrieving files from the db and the underlying file system.
### integration
All integration tests live here.
See [integration tests]({{< ref "test.md" >}}#integration-tests) for more details.
### log
Similar to `config`, this will set up the logging, based on different logging backends.
This init is called in `main.go` after the config init is done.
### mail
This package handles all mail sending. To learn how to send a mail, see [notifications]({{< ref "notifications.md" >}}).
### metrics
This package handles all metrics which are exposed to the prometheus endpoint.
To learn how it works and how to add new metrics, take a look at [how metrics work]({{< ref "metrics.md">}}).
### migration
This package handles all migrations.
All migrations are stored and executed in this package.
To learn more, take a look at the [migrations docs]({{< ref "../development/db-migrations.md">}}).
### models
This is where most of the magic happens.
When adding new features or upgrading existing ones, that most likely happens here.
Because this package is pretty huge, there are several documents and how-to's about it:
* [Adding a feature]({{< ref "feature.md">}})
* [Making calls to the database]({{< ref "database.md">}})
### modules
Everything that can have multiple implementations (like a task migrator from a third-party task provider) lives in a
respective sub package in this package.
#### auth
Contains openid related authentication.
#### avatar
Contains all possible avatar providers a user can choose to set their avatar.
#### background
All project background providers are in sub-packages of this package.
#### dump
Handles everything related to the `dump` and `restore` commands of Vikunja.
#### keyvalue
A simple key-value store with an implementation for memory and redis.
Can be used to cache values.
#### migration
See [writing a migrator]({{< ref "migration.md" >}}).
### red (redis)
This package initializes a connection to a redis server.
This initialization is automatically done at the startup of Vikunja.
It also has a function (`GetRedis()`) which returns a redis client object you can then use in your package
to talk to redis.
It uses the [go-redis](https://github.com/go-redis/redis) library, please see their configuration on how to use it.
**Note**: Only use this package directly if you have to use a direct redis connection.
In most cases, using the `keyvalue` package is a better fit.
### routes
This package defines all routes which are available for Vikunja clients to use.
To add a new route, see [adding a new route]({{< ref "feature.md">}}).
#### api/v1
This is where all http-handler functions for the api are stored.
Every handler function which does not use the standard web handler should live here.
### swagger
This is where the [generated]({{< ref "mage.md#generate-swagger-definitions-from-code-comments">}}) [api docs]({{< ref "../usage/api.md">}}) live.
You usually don't need to touch this package.
### user
All user-related things like registration etc. live in this package.
### utils
A small package, containing some helper functions:
* `MakeRandomString`: Generates a random string of a given length.
* `Sha256`: Calculates a sha256 hash from a given string.
See their function definitions for instructions on how to use them.
### version
The single purpose of this package is to hold the current Vikunja version which gets overridden through build flags each time `mage release` or `mage build` is run.
It is a separate package to avoid import cycles with other packages.
// The id of the file this project has set as background
BackgroundFileID int64 `xorm:"null" json:"-"`
// Holds extra information about the background set since some background providers require attribution or similar. If not null, the background can be accessed at /projects/{projectID}/background
// Contains a very small version of the project background to use as a blurry preview until the actual background is loaded. Check out https://blurha.sh/ to learn how it works.
The following parts are about the kinds of tests in the API package and how to run them.
### Prerequesites
To run any kind of test, you need to specify Vikunja's [root path](https://vikunja.io/docs/config-options/#rootpath).
This is required to make sure all test fixtures are correctly loaded.
The easies way to do that is to set the environment variable `VIKUNJA_SERVICE_ROOTPATH` to the path where you cloned the working directory.
### Unit tests
To run unit tests with [mage]({{< ref "mage.md">}}), execute
```
mage test:unit
```
In Vikunja, everything that is not an integration test counts as unit test - even if it accesses the db.
This definition is a bit blurry, but we haven't found a better one yet.
### Integration tests
All integration tests live in `pkg/integrations`.
You can run them by executing `mage test:integration`.
The integration tests use the same config and fixtures as the unit tests and therefor have the same options available,
see at the beginning of this document.
To run integration tests, use `mage test:integration`.
### Running tests with config
You can run tests with all available config variables if you want, enabling you to run tests for a lot of scenarios.
We use this in CI to run all tests with different databases.
To use the normal config set the environment variable `VIKUNJA_TESTS_USE_CONFIG=1`.
### Showing sql queries
When the environment variable `UNIT_TESTS_VERBOSE=1` is set, all sql queries will be shown during the test run.
### Fixtures
All tests are run against a set of db fixtures.
These fixtures are defined in `pkg/models/fixtures` in YAML-Files which represent the database structure.
When you add a new test case which requires new database entries to test against, update these files.
#### Initializing db fixtures when writing tests
All db fixtures for all tests live in the `pkg/db/fixtures/` folder as yaml files.
Each file has the same name as the table the fixtures are for.
You should put new fixtures in this folder.
When initializing db fixtures, you are responsible for defining which tables your package needs in your test init function.
Usually, this is done as follows (this code snippet is taken from the `user` package):
```go
err = db.InitTestFixtures("users")
if err != nil {
log.Fatal(err)
}
```
In your actual tests, you then load the fixtures into the in-memory db like so:
```go
db.LoadAndAssertFixtures(t)
```
This will load all fixtures you defined in your test init method.
You should always use this method to load fixtures, the only exception is when your package tests require extra test
fixtures other than db fixtures (like files).
## Frontend tests
The frontend has end to end tests with Cypress that use a Vikunja instance and drive a browser against it.
Check out the docs [in the frontend repo](https://kolaente.dev/vikunja/vikunja/src/branch/main/frontend/cypress/README.md) about how they work and how to get them running.
### Unit Tests
To run the frontend unit tests, run
```
pnpm run test:unit
```
The frontend also has a watcher available that re-runs all unit tests every time you change something.
All translation strings are stored in `src/i18n/lang/`.
New strings should be added only in the `en.json` file.
Strings in other languages will be synced through [crowdin](https://crowdin.com/project/vikunja) and should not be added directly as a PR/commit in the frontend repo.
## Requesting a new language
If you want to start translating Vikunja in a language not yet available in Vikunja, please request the language through the crowdin interface.
If you have issues with this or need a discussion before doing so, please [contact us](https://vikunja.io/contact/) or [start a discussion in the forum](https://community.vikunja.io).
Once at least 50% of all translation strings are translated and approved, they will be added and distributed with the Vikunja frontend for users to select and use Vikunja with them.
To fully build Vikunja from source files, you need to build the api and frontend.
{{< table_of_contents >}}
## General Preparations
1. Make sure you have git installed
2. Clone the repo with `git clone https://code.vikunja.io/vikunja` and switch into the directory.
## Frontend
The code for the frontend is located in the `frontend/` sub folder of the main repo.
1. Make sure you have [pnpm](https://pnpm.io/installation) properly installed on your system.
2. Install all dependencies with `pnpm install`
3. Build the frontend with `pnpm run build`. This will result in a static js bundle in the `dist/` folder.
4. You can either deploy that static js bundle directly, or read on to learn how to bundle it all up in a static binary with the api.
## API
The Vikunja API has no other dependencies than go itself.
That means compiling it boils down to these steps:
1. Make sure [Go](https://golang.org/doc/install) is properly installed on your system. You'll need at least Go `1.21`.
2. Make sure [Mage](https://magefile.org) is properly installed on your system.
3. If you did not build the frontend in the steps before, you need to either do that or create a dummy index file with `mkdir -p frontend/dist && touch index.html`.
4. Run `mage build` in the source of the main repo. This will build a binary in the root of the repo which will be able to run on your system.
### Build for different architectures
To build for other platforms and architectures than the one you're currently on, simply run `mage release` or `mage release:{linux|windows|darwin}`.
More options are available, please refer to the [magefile docs]({{< ref "../development/mage.md">}}) for more details.
It is aimed at beginners and should get you up and running quickly.
We'll use [docker compose](https://docs.docker.com/compose/) to make handling the bunch of containers easier.
> If you have any issues setting up vikunja, please don't hesitate to reach out to us via [matrix](https://riot.im/app/#/room/!dCRiCiLaCCFVNlDnYs:matrix.org?via=matrix.org), the [community forum](https://community.vikunja.io/) or even [email](mailto:hello@vikunja.io).
{{< table_of_contents >}}
## Preparations (optional)
Create a directory for the project where all data and the compose file will live in.
## Create all necessary files
Create a `docker-compose.yml` file with the following contents in your directory:
```yaml
version: '3'
services:
vikunja:
image: vikunja/vikunja
environment:
VIKUNJA_SERVICE_PUBLICURL: http://<the public url where vikunja is reachable>
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_PASSWORD: secret
VIKUNJA_DATABASE_TYPE: mysql
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_DATABASE: vikunja
VIKUNJA_SERVICE_JWTSECRET: <a super secure random secret>
Especially when using mysql, this can happen on first start, because the mysql database container will take a few seconds to start.
Vikunja does not know the container is not ready, therefore it will just try to connect to the db, fail since it is not ready and exit.
If you're using the docker compose example from above, you may notice the `restart: unless-stopped` option at the api service.
This tells docker to restart the api container if it exits, unless you explicitly stop it.
Therefore, it should "magically fix itself" by automatically restarting the container.
After a few seconds (or minutes) you should see a log message like this one from the mariadb container:
```
2020-05-24 11:42:15 0 [Note] mysqld: ready for connections.
Version: '10.4.12-MariaDB-1:10.4.12+maria~bionic' socket: '/var/run/mysqld/mysqld.sock' port: 3306 mariadb.org binary distribution
```
The next restart of Vikunja should be successful.
If not, there might be a different error or a bug with Vikunja, please reach out to us in that case.
(If you have an idea about how we could improve this, we'd like to hear it!)
#### Migration failed: commands out of sync
If you get an error like this one:
```
2020/05/23 15:53:38 Config File "config" Not Found in "[/app/vikunja /etc/vikunja /app/vikunja/.config/vikunja]"
2020/05/23 15:53:38 Using default config.
2020-05-23T15:53:38.762747276Z: CRITICAL ▶ migration/Migrate 002 Migration failed: commands out of sync. Did you run multiple statements at once?
```
This is a mysql issue.
Currently, we don't have a better solution than to completely wipe the database files and start over.
To do this, first stop everything by running `sudo docker-compose down`, then remove the `db/` folder in your current folder with `sudo rm -rf db` and start the whole stack again with `sudo docker-compose up -d`.
## Try it
Head over to `http://<host-ip or url>/api/v1/info` in a browser.
You should see something like this:
```json
{
"version": "v0.23.0",
"frontend_url": "https://try.vikunja.io/",
"motd": "",
"link_sharing_enabled": true,
"max_file_size": "20MB",
"registration_enabled": true,
"available_migrators": [
"vikunja-file",
"ticktick",
"todoist"
],
"task_attachments_enabled": true,
"enabled_background_providers": [
"upload",
"unsplash"
],
"totp_enabled": false,
"legal": {
"imprint_url": "",
"privacy_policy_url": ""
},
"caldav_enabled": true,
"auth": {
"local": {
"enabled": true
},
"openid_connect": {
"enabled": false,
"providers": null
}
},
"email_reminders_enabled": true,
"user_deletion_enabled": true,
"task_comments_enabled": true,
"demo_mode_enabled": true,
"webhooks_enabled": true
}
```
This shows you can reach the api through the api proxy.
Now head over to `http://<host-ip or url>/` which should show the login mask.
## Make it persistent
Currently, Vikunja runs in foreground in your terminal.
For a real-world scenario this is not the best way.
Back in your terminal, stop the stack by pressing `CTRL-C` on your keyboard.
Then run `sudo docker-compose up -d` in your again.
The `-d` flag at the end of the command will tell docker to run the containers in the background.
If you need to check the logs after that, you can run `sudo docker-compose logs`.
Vikunja does not have any default users, you'll need to register and account.
After that, you can use it.
## Tear it all down
If you want to completely stop all containers run `sudo docker-compose down` in your terminal.
## Improve this guide
We'll happily accept suggestions and improvements for this guide.
Please [reach out to us](https://vikunja.io/contact/) if you have any.
This docker compose configuration will run Vikunja with a mariadb database.
It uses a proxy configuration to make it available under a domain.
For all available configuration options, see [configuration]({{< ref "config.md">}}).
Once deployed, you might want to change the [`PUID` and `GUID` settings]({{< ref "install.md">}}#setting-user-and-group-id-of-the-user-running-vikunja) or [set the time zone]({{< ref "config.md">}}#timezone).
After registering all your users, you might also want to [disable the user registration]({{<ref "config.md">}}#enableregistration).
<div class="notification is-warning">
<b>NOTE:</b> If you intend to run Vikunja with mysql and/or to use non-latin characters
<a href="{{< ref "utf-8.md">}}">make sure your db is utf-8 compatible</a>.<br/>
All examples on this page already reflect this and do not require additional work.
</div>
{{< table_of_contents >}}
## PostgreSQL
Vikunja supports postgres, mysql and sqlite as a database backend. The examples on this page use mysql with a mariadb container.
To use postgres as a database backend, change the `db` section of the examples to this:
```yaml
db:
image: postgres:13
environment:
POSTGRES_PASSWORD: secret
POSTGRES_USER: vikunja
volumes:
- ./db:/var/lib/postgresql/data
restart: unless-stopped
```
You'll also need to change the `VIKUNJA_DATABASE_TYPE` to `postgres` on the api container declaration.
<div class="notification is-warning">
<b>NOTE:</b> The mariadb container can sometimes take a while to initialize, especially on the first run. During this time, the api container will fail to start at all. It will automatically restart every few seconds.
</div>
## Sqlite
Vikunja supports postgres, mysql and sqlite as a database backend. The examples on this page use mysql with a mariadb container.
To use sqlite as a database backend, change the `api` section of the examples to this:
```yaml
vikunja:
image: vikunja/vikunja
environment:
VIKUNJA_SERVICE_JWTSECRET: <a super secure random secret>
VIKUNJA_SERVICE_PUBLICURL: http://<your public frontend url with slash>/
# Note the default path is /app/vikunja/vikunja.db.
# This config variable moves it to a different folder so you can use a volume and
# store the database file outside the container so state is persisted even if the container is destroyed.
VIKUNJA_DATABASE_PATH: /db/vikunja.db
ports:
- 3456:3456
volumes:
- ./files:/app/vikunja/files
- ./db:/db
restart: unless-stopped
```
The default path Vikunja uses for sqlite is relative to the binary, which in the docker container would be `/app/vikunja/vikunja.db`.
The `VIKUNJA_DATABASE_PATH` environment variable moves changes it so that the database file is stored in a volume at `/db`, to persist state across restarts.
You'll also need to remove or change the `VIKUNJA_DATABASE_TYPE` to `sqlite` on the container declaration.
You can also remove the db section.
<div class="notification is-warning">
<b>NOTE:</b> If you'll use your instance with more than a handful of users, we recommend using mysql or postgres.
</div>
## Example without any proxy
This example lets you host Vikunja without any reverse proxy in front of it.
This is the absolute minimum configuration you need to get something up and running.
If you want to make Vikunja available on a domain or need tls termination, check out one of the other examples.
Note that you need to change the [`VIKUNJA_SERVICE_PUBLICURL`]({{< ref "config.md" >}}#publicurl) environment variable to the ip (the docker host you're running this on) is reachable at.
Because the browser you'll use to access the Vikunja frontend uses that url to make the requests, it has to be able to reach that ip + port from the outside.
```yaml
version: '3'
services:
vikunja:
image: vikunja/vikunja
environment:
VIKUNJA_SERVICE_PUBLICURL: http://<the public url where vikunja is reachable>
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_PASSWORD: secret
VIKUNJA_DATABASE_TYPE: mysql
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_DATABASE: vikunja
VIKUNJA_SERVICE_JWTSECRET: <a super secure random secret>
This example assumes [traefik](https://traefik.io) version 2 installed and configured to [use docker as a configuration provider](https://docs.traefik.io/providers/docker/).
We also make a few assumptions here which you'll most likely need to adjust for your traefik setup:
* Your domain is `vikunja.example.com`
* The entrypoint you want to make vikunja available from is called `https`
* The tls cert resolver is called `acme`
```yaml
version: '3'
services:
vikunja:
image: vikunja/vikunja
environment:
VIKUNJA_SERVICE_PUBLICURL: http://<the public url where vikunja is reachable>
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_PASSWORD: supersecret
VIKUNJA_DATABASE_TYPE: mysql
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_DATABASE: vikunja
VIKUNJA_SERVICE_JWTSECRET: <a super secure random secret>
You will need the following `Caddyfile` on your host (or elsewhere, but then you'd need to adjust the proxy mount at the bottom of the compose file):
```conf
vikunja.example.com {
reverse_proxy api:3456
}
```
Note that you need to change the [`VIKUNJA_SERVICE_PUBLICURL`]({{< ref "config.md" >}}#publicurl) environment variable to the ip (the docker host you're running this on) is reachable at.
Because the browser you'll use to access the Vikunja frontend uses that url to make the requests, it has to be able to reach that ip + port from the outside.
Docker Compose config:
```yaml
version: '3'
services:
vikunja:
image: vikunja/vikunja
environment:
VIKUNJA_SERVICE_PUBLICURL: http://<the public url where vikunja is reachable>
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_PASSWORD: secret
VIKUNJA_DATABASE_TYPE: mysql
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_DATABASE: vikunja
VIKUNJA_SERVICE_JWTSECRET: <a super secure random secret>
You should also add 2 empty folders for mariadb and vikunja inside Synology's
docker main folders:
* Docker
* vikunja
* mariadb
Synology has its own GUI for managing Docker containers, but it's easier via docker compose.
To do that, you can
* Either activate SSH and paste the adapted compose file in a terminal (using Putty or similar)
* Without activating SSH as a "custom script" (go to Control Panel / Task Scheduler / Create / Scheduled Task / User-defined script)
* Without activating SSH, by using Portainer (you have to install first, check out [this tutorial](https://www.portainer.io/blog/how-to-install-portainer-on-a-synology-nas) for exmple):
1. Go to **Dashboard / Stacks** click the button **"Add Stack"**
2. Give it the name Vikunja and paste the adapted docker compose file
3. Deploy the Stack with the "Deploy Stack" button:
The docker-compose file we're going to use is exactly the same from the [example without any proxy](#example-without-any-proxy) above.
You may want to change the volumes to match the rest of your setup.
Once deployed, you might want to change the [`PUID` and `GUID` settings]({{< ref "install.md">}}#setting-user-and-group-id-of-the-user-running-vikunja) or [set the time zone]({{< ref "config.md">}}#timezone).
After registering all your users, you might also want to [disable the user registration]({{<ref "config.md">}}#enableregistration).
## Redis
While Vikunja has support to use redis as a caching backend, you'll probably not need it unless you're using Vikunja with more than a handful of users.
To use redis, you'll need to add this to the config examples below:
On this page you will find examples about how to set up Vikunja with a third-party OpenID provider.
To add another example, please [edit this document](https://kolaente.dev/vikunja/vikunja/src/branch/main/docs/content/doc/setup/openid-examples.md) and send a PR.
{{< table_of_contents >}}
## Authelia
Vikunja Config:
```yaml
openid:
enabled: true
redirecturl: https://vikunja.mydomain.com/auth/openid/ <---- slash at the end is important
redirecturl: https://vikunja.mydomain.com/auth/openid/ <---- slash at the end is important
providers:
- name: Google
authurl: https://accounts.google.com
clientid: <google-oauth-client-id>
clientsecret: <google-oauth-client-secret>
```
Google config:
- Navigate to `https://console.cloud.google.com/apis/credentials` in the target project
- Create a new OAuth client ID
- Configure an authorized redirect URI of `https://vikunja.mydomain.com/auth/openid/google`
Note that there currently seems to be no way to stop creation of new users, even when `enableregistration` is `false` in the configuration. This means that this approach works well only with an "Internal Organization" app for Google Workspace, which limits the allowed users to organizational accounts only. External / public applications will potentially allow every Google user to register.
## Keycloak
Vikunja Config:
```yaml
openid:
enabled: true
redirecturl: https://vikunja.mydomain.com/auth/openid/ <---- slash at the end is important
**Note:** The `authurl` that Vikunja requires is not the `Authorize URL` that you can see in the Provider. Vikunja uses Open ID Discovery to find the correct endpoint to use. Vikunja does this by automatically accessing the `OpenID Configuration URL` (usually `https://authentik.mydomain.com/application/o/vikunja/.well-known/openid-configuration`). Use this URL without the `.well-known/openid-configuration` as the `authurl`.
These examples assume you have an instance of Vikunja running on your server listening on port `3456`.
If you've changed this setting, you need to update the server configurations accordingly.
{{< table_of_contents >}}
## NGINX
You may need to adjust `server_name` and `root` accordingly.
```conf
server {
listen 80;
server_name localhost;
location / {
proxy_pass http://localhost:3456;
client_max_body_size 20M;
}
}
```
<div class="notification is-warning">
<b>NOTE:</b> If you change the max upload size in Vikunja's settings, you'll need to also change the <code>client_max_body_size</code> in the nginx proxy config.
</div>
## NGINX Proxy Manager (NPM)
Following the [Docker Walkthrough]({{< ref "docker-start-to-finish.md" >}}) guide, you should be able to get Vikunja to work via HTTP connection to your server IP.
From there, all you have to do is adjust the following things:
### In `docker-compose.yml`
1. Change `VIKUNJA_SERVICE_PUBLICURL:` to your desired domain with `https://` and `/`.
2. Expose your desired port on host under `ports:`.
example:
```yaml
vikunja:
image: vikunja/vikunja
environment:
VIKUNJA_SERVICE_PUBLICURL: https://vikunja.your-domain.com/ # change vikunja.your-domain.com to your desired domain/subdomain.
VIKUNJA_DATABASE_HOST: db
VIKUNJA_DATABASE_PASSWORD: secret
VIKUNJA_DATABASE_TYPE: mysql
VIKUNJA_DATABASE_USER: vikunja
VIKUNJA_DATABASE_DATABASE: vikunja
VIKUNJA_SERVICE_JWTSECRET: <your-random-secret>
ports:
- 3456:3456 # Change 3456 on the left to the port of your choice.
volumes:
- ./files:/app/vikunja/files
depends_on:
- db
restart: unless-stopped
```
### In your DNS provider
Add an `A` records that points to your server IP.
You are of course free to change them to whatever domain/subdomain you desire and modify the `docker-compose.yml` accordingly.
(Tested on Cloudflare DNS. Settings are different for different DNS provider, in this case the end result should be `vikunja.your-domain.com`)
### In Nginx Proxy Manager
Add a Proxy Host as you normally would, and you don't have to add anything extra in Advanced.
Under `Details`:
```
Domain Names:
vikunja.your-domain.com
Scheme:
http
Forward Hostname/IP:
your-server-ip
Forward Port:
3456
Cached Assets:
Optional.
Block Common Exploits:
Toggled.
Websockets Support:
Toggled.
```
Under `SSL`:
```
SSL Certificate:
However you prefer.
Force SSL:
Toggled.
HTTP/2 Support:
Toggled.
HSTS Enabled:
Toggled.
HSTS Subdomains:
Toggled.
Use a DNS Challenge:
Not toggled.
Email Address for Let's Encrypt:
your-email@email.com
```
Your Vikunja service should now work and your HTTPS frontend should be able to reach the API after `docker-compose`.
## Apache
Put the following config in `cat /etc/apache2/sites-available/vikunja.conf`:
```aconf
<VirtualHost *:80>
ServerName localhost
<Proxy *>
Order Deny,Allow
Allow from all
</Proxy>
ProxyPass / http://localhost:3456/
ProxyPassReverse / http://localhost:3456/
</VirtualHost>
```
**Note:** The apache modules `proxy`, `proxy_http` and `rewrite` must be enabled for this.
## Caddy
Use the following Caddyfile to get Vikunja up and running:
Vikunja supports using [Typesense](https://typesense.org/) for a better search experience.
Typesense allows fast fulltext search including fuzzy matching support.
It may return different results than what you'd get with a database-only search, but generally, the results are more relevant to what you're looking for.
This document explains how to set up and use Typesense with Vikunja.
## Setup
1. First, install Typesense on your system. Refer to [their documentation](https://typesense.org/docs/guide/install-typesense.html) for specific instructions.
2. Once Typesense is available on your system and reachable by Vikunja, add the relevant configuration keys to your Vikunja config. [Check out the docs article about this]({{< ref "config.md#typesense">}}).
3. Index all tasks currently in Vikunja. To do that, run the `vikunja index` command with the api binary. This may take a while, depending on the size of your instance.
4. Restart the api. From now on, all task changes will be automatically indexed in Typesense.
Vikunja itself is always fully capable of handling utf-8 characters.
However, your database might be not. Vikunja itself will work just fine until you want to use non-latin characters in your tasks/projects/etc.
On this page, you will find information about how to fully ensure non-latin characters like *aüäß* or emojis work with your installation.
{{< table_of_contents >}}
## Postgresql & SQLite
Postgresql and SQLite should handle utf-8 just fine - If you discover any issues nonetheless, please
[drop us a message](https://vikunja.io/contact/).
## MySQL
MySQL is not able to handle utf-8 by default.
To fix this, follow the steps below.
To find out if your db supports utf-8, run the following in a shell or similar, assuming the database
you're using for vikunja is called `vikunja`:
```sql
SELECT default_character_set_name FROM information_schema.SCHEMATA WHERE schema_name = 'vikunja';
```
This will get you a result like the following:
```
+----------------------------+
| default_character_set_name |
+----------------------------+
| latin1 |
+----------------------------+
1 row in set (0.001 sec)
```
The charset `latin1` means the db is encoded in the `latin1` encoding which does not support utf-8 characters.
(The following guide is based on [this thread from stackoverflow](https://dba.stackexchange.com/a/104866))
### 0. Backup your database
Before attempting any conversion, please [back up your database]({{< ref "backups.md">}}).
### 1. Create a pre-conversion script
Copy the following sql statements in a file called `preAlterTables.sql` and replace all occurrences of `vikunja` with the name of your database:
```sql
use information_schema;
SELECT concat("ALTER DATABASE `",table_schema,"` CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;") as _sql
FROM `TABLES` where table_schema like 'vikunja' and TABLE_TYPE='BASE TABLE' group by table_schema;
SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name,"` CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;") as _sql
FROM `TABLES` where table_schema like 'vikunja' and TABLE_TYPE='BASE TABLE' group by table_schema, table_name;
SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name, "` CHANGE `",column_name,"``",column_name,"` ",data_type,"(",character_maximum_length,") CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci",IF(is_nullable="YES"," NULL"," NOT NULL"),";") as _sql
FROM `COLUMNS` where table_schema like 'vikunja' and data_type in ('varchar','char');
SELECT concat("ALTER TABLE `",table_schema,"`.`",table_name, "` CHANGE `",column_name,"``",column_name,"` ",data_type," CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci",IF(is_nullable="YES"," NULL"," NOT NULL"),";") as _sql
FROM `COLUMNS` where table_schema like 'vikunja' and data_type in ('text','tinytext','mediumtext','longtext');
```
### 2. Run the pre-conversion script
Running this will create the actual migration script for your particular database structure and save it in a file called `alterTables.sql`:
```
mysql -uroot < preAlterTables.sql | egrep '^ALTER' > alterTables.sql
```
### 3. Convert the database
At this point converting is just a matter of executing the previously generated sql script:
```
mysql -uroot < alterTables.sql
```
### 4. Verify it was successfully converted
If everything worked as intended, your db collation should now look like this:
```sql
SELECT default_character_set_name FROM information_schema.SCHEMATA WHERE schema_name = 'vikunja';
The Vikunja api and frontend are available in two different release flavors.
{{< table_of_contents >}}
## Stable
Stable releases have a fixed version number like `0.18.2` and are published at irregular intervals whenever a new version is ready.
They receive few bugfixes and security patches.
We use [Semantic Versioning](https://semver.org) for these releases.
## Unstable
Unstable versions are build every time a PR is merged or a commit to the main development branch is made.
As such, they contain the current development code and are more likely to have bugs.
There might be multiple new such builds a day.
Versions contain the last stable version, the number of commits since then and the commit the currently running binary was built from.
They look like this: `v0.18.1+269-5cc4927b9e`
The demo instance at [try.vikunja.io](https://try.vikunja.io) automatically updates and always runs the last unstable build.
## Switching between versions
First you should create a backup of your current setup!
Switching between versions is the same process as [upgrading]({{< ref install.md >}}#updating).
Simply replace the stable binary with an unstable one or vice-versa.
For installations using docker, it is as simple as using the `unstable` or `latest` tag to switch between versions.
**Note:** While switching from stable to unstable should work without any problem, switching back might work but is not recommended and might break your instance.
To switch from unstable back to stable the best way is to wait for the next stable release after the used unstable build and then upgrade to that.
You can interact with Vikunja using its `cli` interface.<br />
The following commands are available:
* [dump](#dump)
* [help](#help)
* [migrate](#migrate)
* [restore](#restore)
* [testmail](#testmail)
* [user](#user)
* [version](#version)
* [web](#web)
If you don't specify a command, the [`web`](#web) command will be executed.
All commands use the same standard [config file]({{< ref "../setup/config.md">}}).
## Using the cli in docker
When running Vikunja in docker, you'll need to execute all commands in the `api` container.
Instead of running the `vikunja` binary directly, run it like this:
```sh
docker exec <name of the vikunja api container> /app/vikunja/vikunja <subcommand>
```
### `dump`
Creates a zip file with all vikunja-related files.
This includes config, version, all files and the full database.
Usage:
```
$ vikunja dump
```
### `help`
Shows more detailed help about any command.
Usage:
```
$ vikunja help [command]
```
### `migrate`
Run all database migrations which didn't already run.
Usage:
```
$ vikunja migrate [flags]
$ vikunja migrate [command]
```
#### `migrate list`
Shows a list with all database migrations.
Usage:
```
$ vikunja migrate list
```
#### `migrate rollback`
Roll migrations back until a certain point.
Usage:
```
$ vikunja migrate rollback [flags]
```
Flags:
* `-n`, `--name` string: The id of the migration you want to roll back until.
### `restore`
Restores a previously created dump from a zip file, see `dump`.
Usage:
```
$ vikunja restore <path to dump zip file>
```
### `testmail`
Sends a test mail using the configured smtp connection.
Usage:
```
$ vikunja testmail <email to send the test mail to>
```
### `user`
Bundles a few commands to manage users.
#### `user change-status`
Enable or disable a user. Will toggle the current status if no flag (`--enable` or `--disable`) is provided.
Usage:
```
$ vikunja user change-status <user id> <flags>
```
Flags:
* `-d`, `--disable`: Disable the user.
* `-e`, `--enable`: Enable the user.
#### `user create`
Create a new user.
Usage:
```
$ vikunja user create <flags>
```
Flags:
* `-a`, `--avatar-provider`: The avatar provider of the new user. Optional.
* `-e`, `--email`: The email address of the new user.
* `-p`, `--password`: The password of the new user. You will be asked to enter it if not provided through the flag.
* `-u`, `--username`: The username of the new user.
#### `user delete`
Start the user deletion process.
If called without the `--now` flag, this command will only trigger an email to the user in order for them to confirm and start the deletion process (this is the same behavoir as if the user requested their deletion via the web interface).
With the flag the user is deleted **immediately**.
**USE WITH CAUTION.**
```
$ vikunja user delete <id> <flags>
```
Flags:
* `-n`, `--now` If provided, deletes the user immediately instead of emailing them first.
#### `user list`
Shows a list of all users.
Usage:
```
$ vikunja user list
```
#### `user reset-password`
Reset a users password, either through mailing them a reset link or directly.
Usage:
```
$ vikunja user reset-password <flags>
```
Flags:
* `-d`, `--direct`: If provided, reset the password directly instead of sending the user a reset mail.
* `-p`, `--password`: The new password of the user. Only used in combination with --direct. You will be asked to enter it if not provided through the flag.
#### `user update`
Update an existing user.
Usage:
```
$ vikunja user update <user id>
```
Flags:
* `-a`, `--avatar-provider`: The new avatar provider of the new user.
* `-e`, `--email`: The new email address of the user.
* `-u`, `--username`: The new username of the user.
### `version`
Prints the version of Vikunja.
This is either the semantic version (something like `0.7`) or version + git commit hash.
Starting with version 0.22.0, Vikunja allows you to define webhooks to notify other services of events happening within Vikunja.
{{< table_of_contents >}}
## How to create webhooks
To create a webhook, in the project options select "Webhooks". The form will allow you to create and modify webhooks.
Check out [the api docs](https://try.vikunja.io/api/v1/docs#tag/webhooks) for information about how to create webhooks programatically.
## Available events and their payload
All events registered as webhook events in [the event listeners definition](https://kolaente.dev/vikunja/vikunja/src/branch/main/pkg/models/listeners.go#L69) can be used as webhook target.
A webhook payload will look similar to this:
```json
{
"event_name": "task.created",
"time": "2023-10-17T19:39:32.924194436+02:00",
"data": {}
}
```
The `data` property will contain the raw event data as it was registered in the `listeners.go` file.
The `time` property holds the time when the webhook payload data was sent.
It always uses the ISO 8601 format with date, time and time zone offset.
## Security considerations
### Signing
Vikunja allows you to provide a secret when creating the webhook.
If you set a secret, all outgoing webhook requests will contain an `X-Vikunja-Signature` header with an HMAC signature over the webhook json payload.
Check out [webhooks.fyi](https://webhooks.fyi/security/hmac) for more information about how to validate the HMAC signature.
### Hosting webhook infrastructure
Vikunja has support to use [mole](https://github.com/frain-dev/mole) as a proxy for outgoing webhook requests.
This allows you to prevent SSRF attacts on your own infrastructure.
You should use this and [configure it appropriately]({{< ref "../setup/config.md">}}#webhooks) if you're not the only one using your Vikunja instance.
Check out [webhooks.fyi](https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication) for more information about the attack vector and reasoning to prevent this.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
kolaente
jdandkolaente
renovateandkolaente
Frederick [Bot]andkolaente
Dominik Pschenitschniandkolaente
Balázs Kereszturyandkonrad
andreymalandkonrad
David Baakmanandkonrad
treysulliventandkonrad
Raymi306andkonrad
Hangyaandkonrad
Christoph Ritzerandkonrad
viehliebandkonrad
