Skip to content

Migration Guide (Released)

All migrations of webKnossos are documented in this file. See MIGRATIONS.unreleased.md for the changes which are not yet part of an official release.

This project adheres to Calendar Versioning 0Y.0M.MICRO. User-facing changes are documented in the changelog.

21.09.0 - 2021-10-01

  • For webknossos.org: Change publicDemoDatasetUrl in the features-block within application.conf to be an actionable URL. For example, append /createExplorative/hybrid?fallbackLayerName=segmentation to the URL so that a new annotation is created if a user clicks on Open a Demo Dataset in the dashboard.

Postgres Evolutions:

21.08.0 - 2021-08-26

Commits No migrations necessary.

21.07.0 - 2021-07-21

  • Consider setting defaultToLegacyBindings to true in application.conf if you want that new users use the classic controls by default.
  • To make the classic mouse bindings the default for existing users and task types execute the following (adapt true to false if you want the opposite):
-- Activate legacy bindings for all users
UPDATE webknossos.users
SET userconfiguration = jsonb_set(
        userconfiguration,
        array['useLegacyBindings'],
        to_jsonb('true'::boolean))

-- Recommend legacy bindings for users when starting a new task
UPDATE webknossos.tasktypes
SET recommendedconfiguration = jsonb_set(
        recommendedconfiguration,
        array['useLegacyBindings'],
        to_jsonb('true'::boolean))
  • The health check at api/health does not longer include checking data/health and tracings/health if the respective local modules are enabled. Consider monitoring those routes separately.
  • Run as sql: UPDATE webknossos.tasktypes SET recommendedconfiguration = recommendedconfiguration - 'highlightHoveredCellId'; to avoid invalid recommended configurations in existing task types. This was added later as evolution 75, but should be run already here (note that it is idempotent).

Postgres Evolutions:

21.06.0 - 2021-06-01

Postgres Evolutions:

21.05.1 - 2021-05-05

  • The config keys in application.conf were restructured. If you overwrite any of them for your config, please adapt to the new structure, according to the table below. If you run any stand-alone datastores or tracingstores, make sure to update their config files as well.
old key new key notes
http.address removed used by play, default is 0.0.0.0, you can still overwrite it if necessary
actor.defaultTimeout removed was already unused
js.defaultTimeout removed was already unused
akka.loggers removed was already unused
application.name removed was already unused
application.branch removed was already unused
application.version removed was already unused
application.title webKnossos.tabTitle
application.insertInitialData webKnossos.sampleOrganization.enabled
application.insertLocalConnectDatastore removed feature removed, insert manually instead
application.authentication.defaultuser.email webKnossos.sampleOrganization.user.email
application.authentication.defaultUser.password webKnossos.sampleOrganization.user.password
application.authentication.defaultUser.token webKnossos.sampleOrganization.user.token
application.authentication.defaultUser.isSuperUser webKnossos.sampleOrganization.user.isSuperUser
application.authentication.ssoKey webKnossos.user.ssoKey
application.authentication.inviteExpiry webKnossos.user.inviteExpiry
webKnossos.user.time.tracingPauseInSeconds webKnossos.user.time.tracingPause type changed from Int to FiniteDuration, add seconds
webKnossos.query.maxResults removed was already unused
user.cacheTimeoutInMinutes webKnossos.cache.user.timeout type changed from Int to FiniteDuration, add minutes
tracingstore.enabled removed info contained in play.modules.enabled
datastore.enabled removed info contained in play.modules.enabled
datastore.webKnossos.pingIntervalMinutes datastore.webKnossos.pingInterval type changed from Int to FiniteDuration, add minutes
braingames.binary.cacheMaxSize datastore.cache.dataCube.maxEntries
braingames.binary.mappingCacheMaxSize datastore.cache.mapping.maxEntries
braingames.binary.agglomerateFileCacheMaxSize datastore.cache.agglomerateFile.maxFileHandleEntries
braingames.binary.agglomerateCacheMaxSize datastore.cache.agglomerateFile.maxSegmentIdEntries
braingames.binary.agglomerateStandardBlockSize datastore.cache.agglomerateFile.blockSize
braingames.binary.agglomerateMaxReaderRange datastore.cache.agglomerateFile.cumsumMaxReaderRange
braingames.binary.loadTimeout removed was already unused
braingames.binary.saveTimeout removed was already unused
braingames.binary.isosurfaceTimeout datastore.isosurface.timeout type changed from Int to FiniteDuration, add seconds
braingames.binary.isosurfaceActorPoolSize datastore.isosurface.actorPoolSize
braingames.binary.baseFolder datastore.baseFolder
braingames.binary.agglomerateSkeletonEdgeLimit datastore.agglomerateSkeleton.maxEdges
braingames.binary.changeHandler.enabled datastore.watchFileSystem.enabled
braingames.binary.tickerInterval datastore.watchFileSystem.interval type changed from Int to FiniteDuration, add minutes
mail.enabled removed now enabled if mail.host is non-empty
jobs.username jobs.user
braintracing.active braintracing.enabled
braintracing.url braintracing.uri
airbrake.apiKey removed was already unused
airbrake.ssl removed was already unused
airbrake.enabled removed was already unused
airbrake.endpoint removed was already unused
slackNotifications.url slackNotifications.uri
google.analytics.trackingId googleAnalytics.trackingId
operatorData webKnossos.operatorData

Postgres Evolutions:

21.05.0 - 2021-04-22

  • Instances with long-running jobs only: the tiff_cubing job was renamed to convert_to_wkw. For old jobs to be listed properly, execute sql update webknossos.jobs set command = 'convert_to_wkw' where command = 'tiff_cubing';

Postgres Evolutions:

21.04.0 - 2021-03-22

Postgres Evolutions:

21.03.0 - 2021-02-24

  • Support for KNOSSOS cubes data format was removed. Use the webKnossos cuber tool to convert existing datasets saved as KNOSSOS cubes.
  • Multi-organization instances only: user experience domains are now separated per organization. After postgres evolution 64 (see below), make sure to move existing experience domains to the correct organization in the database. (The evolution just selects any one from the database).

Postgres Evolutions:

21.02.1 - 2021-02-03

Commits No migrations necessary.

21.02.0 - 2021-01-20

  • 060-multiusers.sql (Note that its reversion can only be performed if there are no multiple users per multiuser yet)

21.01.0 - 2020-12-21

No migrations necessary.

20.12.0 - 2020-11-23

  • As volume annotations in arbitrary magnifications are now supported and the behavior of magnification restrictions of tasks has changed (allow full zoom, but disable tools unless in correct magnification), you may want to restrict all volume and hybrid task types to mag 1 to achieve the old behavior (mag1-only). NOTE: This query has to be executed BEFORE evolution 59 is performed.
update webknossos.tasktypes
set settings_allowedmagnifications = '{"min":1,"max":1,"shouldRestrict":true}'
where (tracingtype = 'volume' or tracingtype = 'hybrid')
and (settings_allowedmagnifications is null or settings_allowedmagnifications::json->>'shouldRestrict'='false');

Postgres Evolutions:

20.11.0 - 2020-10-26

20.10.0 - 2020-09-21

No migrations necessary.

20.09.0 - 2020-08-20

No migrations necessary.

20.08.0 - 2020-07-20

Postgres Evolutions:

20.07.0 - 2020-06-29

No migrations necessary.

20.06.0 - 2020-05-25

Postgres Evolutions:

20.05.0 - 2020-05-05

  • The optional defaultOrganization attribute from the features block in application.conf is not used anymore and can be removed. #4559

20.04.0 - 2020-03-23

  • Default interval for detecting new/deleted datasets on disk (braingames.binary.changeHandler.tickerInterval in the config) has been reduced from 10 to 1 minute. If you relied on the value being 10 minutes, you have to set it explicitly now.

Postgres Evolutions:

20.03.0 - 2020-02-27

No migrations necessary.

20.2.0 - 2020-01-27

Postgres Evolutions:

20.1.0 - 2020-01-08

  • The initial organization was renamed to sample_organization. Make sure to move the data over or to put a symlink in place.
  • The default operatorData was replaced. Make sure to update with valid information for public deployments.
  • The config uri has been refactored. Pairs of uri and secured have been replaced with just uri which now requires a http:// or https:// prefix.

Postgres Evolutions:

19.12.0 - 2019-11-25

No migrations necessary.

19.11.0 - 2019-10-28

Postgres Evolutions:

19.10.0 - 2019-09-30

Postgres Evolutions:

19.09.0 - 2019-08-28

No migrations necessary.

19.08.0 - 2019-07-29

No migrations necessary.

19.07.0 - 2019-07-01

Postgres Evolutions:

19.06.0 - 2019-05-27

No migrations necessary.

19.05.0 - 2019-04-29

Postgres Evolutions:

19.04.0 - 2019-04-01

  • Redis is now needed for the tracingstore module. Make sure to install redis in your setup and adapt the config keys tracingstore.redis.address and tracingstore.redis.port.
  • To ensure that the existing behavior for loading data is preserved ("best quality first" as opposed to the new "progressive quality" default) execute: update webknossos.user_datasetconfigurations set configuration = configuration || jsonb '{"loadingStrategy":"BEST_QUALITY_FIRST"}'. See #3801 for additional context.
  • The config parameter application.title has been added. Make sure to set a title for your instance.
  • The assets URLs now include assets/ again, if you link to assets directly, please update the paths (e.g. in postgres organizations.logoUrl)

Postgres Evolutions:

19.03.0 - 2019-03-04

  • The config paramters application.authentication.enableDevAutoVerify and application.authentication.enableDevAutoAdmin have been removed. To enable automatic verification for user signup, set the organization’s new enableAutoVerify field to true in the database.

Postgres Evolutions:

19.02.0 - 2019-02-04

  • WebKnossos has a publication gallery now. There is no public interface to create publications yet, but instead those need to be inserted into the database directly. Publications and additional dataset properties that are displayed in the gallery as well, can be inserted as follows: ``` insert into webknossos.publications(_id, publicationDate, imageUrl, title, description) values('5c3c9ec895010095014759fd', NOW(), '', '', '<DESCRIPTION>');</li> </ul> <p>update webknossos.datasets set _publication = '5c3c9ec895010095014759fd', details='{"species":"<e.g. Mouse>", "brain-region":"<e.g. cortex>", "acquisition":"<e.g. Raw CLSM data>"}' where _id = '<DATASET_ID>' ; ```</p> <h3 id="postgres-evolutions_19">Postgres Evolutions:</h3> <ul> <li><a href="conf/evolutions/037-add-publications.sql">037-add-publications.sql</a></li> </ul> <h2 id="19010-2019-01-14"><a href="https://github.com/scalableminds/webknossos/releases/tag/19.01.0">19.01.0</a> - 2019-01-14</h2> <h3 id="postgres-evolutions_20">Postgres Evolutions:</h3> <ul> <li><a href="conf/evolutions/036-add-lastTaskTypeId-to-user.sql">036-add-lastTaskTypeId-to-user.sql</a></li> </ul> <h2 id="18120-2018-11-26"><a href="https://github.com/scalableminds/webknossos/releases/tag/18.12.0">18.12.0</a> - 2018-11-26</h2> <ul> <li>If additional dataset directories were watched using the config key <code>additionalFolders</code>, those symlinks are no longer updated. Consider setting up additional datastores for these directories respectively.</li> </ul> <h3 id="postgres-evolutions_21">Postgres Evolutions:</h3> <ul> <li><a href="conf/evolutions/033-tasktype-recommendedConfiguration.sql">033-tasktype-recommendedConfiguration.sql</a></li> <li><a href="conf/evolutions/034-meshes.sql">034-meshes.sql</a></li> <li><a href="conf/evolutions/035-add-annotation-dataset-foreign-key.sql">035-add-annotation-dataset-foreign-key.sql</a></li> </ul> <h2 id="18110-2018-10-29"><a href="https://github.com/scalableminds/webknossos/releases/tag/18.11.0">18.11.0</a> - 2018-10-29</h2> <ul> <li>Some config keys have changed, if you overwrite them in your setup, please adapt: the <code>oxalis</code> prefix is renamed to <code>webKnossos</code> so the new keys are <code>webKnossos.user.time.tracingPauseInSeconds</code>, <code>webKnossos.tasks.maxOpenPerUser</code>, <code>webKnossos.newOrganizationMailingList</code> as well as <code>datastore.webKnossos.uri</code>, <code>datastore.webKnossos.secured</code>, <code>datastore.webKnossos.pingIntervalMinutes</code> for the data store.</li> <li>There is now a separate module for the tracingstore, the datastore is no longer responsible for saving tracings. This module can run as a standalone application, or as a module of webKnossos locally. It is recommended that you choose the option that was previously also in place for datastores. In case of a standalone datastore, the local one needs to be disabled in application.conf: <code>tracingstore.enabled = false</code> and <code>play.modules.disabled += "com.scalableminds.braingames.datastore.TracingStoreModule</code> – and in either case, the adress of the tracingstore (localhost or remote) needs to be inserted in the db in <code>webknossos.tracingStores</code>.</li> <li>The FossilDB version has changed from <code>0.1.10</code> to <code>0.1.14</code>.</li> <li>The FossilDB needs to be run with an additional column family <code>volumeUpdates</code>.</li> <li>If your setup overwrites the config key <code>play.http.router</code> to disable the local datastore, change it to <code>"noDS.Routes"</code> (or <code>"noDS.noTS.Routes"</code> to also disable the local tracingstore).</li> </ul> <h4 id="postgres-evolutions_22">Postgres Evolutions:</h4> <ul> <li><a href="conf/evolutions/027-drop-dataset-name-unique-constraint.sql">027-drop-dataset-name-unique-constraint.sql</a></li> <li><a href="conf/evolutions/028-add-isBlacklistedFromReport.sql">028-add-isBlacklistedFromReport.sql</a></li> <li><a href="conf/evolutions/029-foreign-keys-deferrable.sql">029-foreign-keys-deferrable.sql</a></li> <li><a href="conf/evolutions/030-tracingstore.sql">030-tracingstore.sql</a></li> <li><a href="conf/evolutions/031-maintenance.sql">031-maintenance.sql</a></li> <li><a href="conf/evolutions/032-scratch-datastores.sql">032-scratch-datastores.sql</a></li> </ul> <h2 id="18100-2018-09-22"><a href="https://github.com/scalableminds/webknossos/releases/tag/18.10.0">18.10.0</a> - 2018-09-22</h2> <h3 id="postgres-evolutions_23">Postgres Evolutions:</h3> <ul> <li><a href="conf/evolutions/022-add-foreign-datastore.sql">022-add-foreign-datastore.sql</a></li> <li><a href="conf/evolutions/023-drop-datastore-type.sql">023-drop-datastore-type.sql</a></li> <li><a href="conf/evolutions/024-drop-md5hash.sql">024-drop-md5hash.sql</a></li> <li><a href="conf/evolutions/025-add-dataset-sortingKey.sql">025-add-dataset-sortingKey.sql</a></li> <li><a href="conf/evolutions/026-decrease-total-instance.sql">026-decrease-total-instance.sql</a></li> </ul> <h3 id="configuration-changes">Configuration Changes:</h3> <ul> <li>some keys in <code>application.conf</code> have changed, if you overwrite them in your setup, please adapt: <code>application.secret</code> is now <code>play.http.secret.key</code>, <code>postgres.*</code> is now <code>slick.db.*</code></li> <li>Logger configuration has been simplified. Webknossos no longer comes with multiple logger config xmls, so if your setup selected a specific one of these, that needs to be removed (or a custom file needs to be supplied). Same for standalone datastore.</li> </ul> <h3 id="data-migrations">Data Migrations:</h3> <ul> <li>Use <code>tools/volumeAddFallbackLayer.py</code> to add a fallback segmentation layer to existing volume tracing zip files (also compare CHANGELOG.md).</li> </ul> <h2 id="18090-2018-08-20"><a href="https://github.com/scalableminds/webknossos/releases/tag/18.09.0">18.09.0</a> - 2018-08-20</h2> <h3 id="postgres-evolutions_24">Postgres Evolutions:</h3> <ul> <li><a href="conf/evolutions/018-hybrid-annotations.sql">018-hybrid-annotations.sql</a></li> <li><a href="conf/evolutions/019-dataset-lastusedtime.sql">019-dataset-lastusedtime.sql</a></li> <li><a href="conf/evolutions/021-list-experiences.sql">021-list-experiences.sql</a></li> </ul> <h2 id="18080-2018-07-23"><a href="https://github.com/scalableminds/webknossos/releases/tag/18.08.0">18.08.0</a> - 2018-07-23</h2> <h3 id="postgres-evolutions_25">Postgres Evolutions:</h3> <ul> <li><a href="conf/evolutions/013-add-logoUrl.sql">013-add-logoUrl.sql</a></li> <li><a href="conf/evolutions/014-equalize-schema-and-evolutions.sql">014-equalize-schema-and-evolutions.sql</a></li> <li><a href="conf/evolutions/015-add-organization-displayname.sql">015-add-organization-displayname.sql</a></li> <li>To clean up half-deleted tasks as caused by <a href="https://github.com/scalableminds/webknossos/issues/2873">this bug</a>, run <code>update webknossos.annotations set isDeleted = true where _id in (select a._id from webknossos.annotations_ a join webknossos.tasks t on a._task = t._id where t.isDeleted and a.typ == 'Task')</code></li> <li><a href="conf/evolutions/016-add-schema-version.sql">016-add-schema-version.sql</a></li> <li><a href="conf/evolutions/017-add-organization-email.sql">017-add-organization-email.sql</a></li> <li>Add email addresses for notifications about new users and about task overtime to the <code>webknossos.organizations</code> entries in the Postgres database (previously in <code>application.conf</code> > <code>braintracing.newuserlist</code> and <code>braintracing.overTimeList</code>)</li> </ul> <h2 id="18070-2018-07-05"><a href="https://github.com/scalableminds/webknossos/releases/tag/18.07.0">18.07.0</a> - 2018-07-05</h2> <p>First release</p> </article> </div> </div> <a href="#" class="md-top md-icon" data-md-component="top" data-md-state="hidden"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"/></svg> Back to top </a> </main> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "..", "features": ["navigation.instant", "navigation.tabs", "navigation.sections", "navigation.top"], "translations": {"clipboard.copy": "Copy to clipboard", "clipboard.copied": "Copied to clipboard", "search.config.lang": "en", "search.config.pipeline": "trimmer, stopWordFilter", "search.config.separator": "[\\s\\-]+", "search.placeholder": "Search", "search.result.placeholder": "Type to start searching", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.term.missing": "Missing", "select.version.title": "Select version"}, "search": "../assets/javascripts/workers/search.409db549.min.js", "version": null}</script> <script src="../assets/javascripts/bundle.756773cc.min.js"></script> </body> </html>