From b7cdaa9a2181e4098bc38ccd533f95775049527c Mon Sep 17 00:00:00 2001 From: Juri Leino Date: Mon, 5 Aug 2024 12:44:10 +0300 Subject: [PATCH] docs: update readme --- README.md | 132 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 82 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 1a3aa15..6ad2238 100644 --- a/README.md +++ b/README.md @@ -31,8 +31,8 @@ To initialize the project and load dependencies run | Run | Description | |---------|-------------| -|```gulp build```|to just build Tuttle. | -|```gulp install```|To build and install Tuttle in one go| +|```npm run build```|to just build Tuttle. | +|```npm run deploy```|To build and install Tuttle in one go| The resulting xar(s) are found in the root of the project. @@ -45,49 +45,78 @@ Run tests with ```npm test``` Tuttle is configured in `data/tuttle.xml`. -### Gitservice configuration -@name is always the name of the destination collection. It will be configured in `data/tuttle.xml` +New with version 2.0.0: + +A commented example configuration is available `data/tuttle-example-config.xml`. +If you want to update tuttle your modified configuration file will be backed up to +`/db/tuttle-backup/tuttle.xml` and restored on installation of the new version. + +Otherwise, when no back up of an existing config-file is found, the example configuration is copied to `data/tuttle.xml`. + +> [!TIP] +> When migrating from an earlier version you can copy your existing configuration to the backup location: +> `xmldb:copy-resource('/db/apps/tuttle/data', 'tuttle.xml', '/db/tuttle-backup', 'tuttle.xml')` + +### Repository configuration + +The repositories to keep in sync with a gitservice are all listed under the repos-element. + +The name-attribute refers to the **destination collection** also known as the **target collection**. + +#### Collection + +An example: `` +The collection `/db/apps/tuttle-sample-data` is now considered to be kept in sync with a git repository. -An example: ```xml - - - true - github - https://api.github.com/ - tuttle-sample-data - tuttle-sample-data - - master - admin - - - - - gitlab - https://gitlab.com/api/v4/ - tuttle-sample-data - XXX - master - admin - - - + + true + + github + https://api.github.com/ + + tuttle-sample-data + tuttle-sample-data + + a-personal-access-token + + a-branch + + a-exist-user + that-users-password + ``` #### type -Gitserver type: 'github' or 'gitlab' -#### baseurl -* For github the baseurl is always api.github.com -* For gitlab the url can also be your private gitlab server egg 'https://gitlab.existsolutions.com/api/v4/' +```xml +gitlab +``` + +There are two supported git services at the moment `github` and `gitlab` + +#### baseurl + +```xml +https://api.server/ +``` -#### repo, owner and project-id - * For github you have to specify the owner and the repo - * For gitlab you have to specify the project-id of the repository +* For github the baseurl is `https://api.github.com/` or your github-enterprise API endpoint +* For gitlab the baseurl is `https://gitlab.com/api/v4/` but can also be your private gitlab server egg 'https://gitlab.existsolutions.com/api/v4/' -#### ref -Define the working branch of the git repository +#### repo, owner and project-id + +* For github you **have to** specify the owner and the repo +* For gitlab you **have to** specify the project-id of the repository + + +#### ref + +```xml +main +``` + +Defines the branch you want to track. #### hookuser & hookpasswd @@ -95,13 +124,12 @@ Define the working branch of the git repository If a token is specified Tuttle authenticates against GitHub or GitLab. When a token is not defined, Tuttle assumes a public repository without any authentication. -It is also possible to pass the token via an environment variable. The name of the variable have to be `tuttle_token_ + collection` (all dashes must be replaces by underscore). Example: `tuttle_token_tuttle_sample_data` - -Be aware of the rate limits -* GitHub: - * 60 unauthenticated requests per hour - * 5,000 authenticated requests per hour +> [!NOTE] +> Be aware of the rate limits for unauthenticated requests +> GitHub allows 60 unauthenticated requests per hour but 5,000 for authenticated requests +> [!TIP] +> It is also possible to pass the token via an environment variable. The name of the variable have to be `tuttle_token_ + collection` (all dashes must be replaces by underscore). Example: `tuttle_token_tuttle_sample_data` ##### Create API-Keys for Github / Gitlab @@ -123,17 +151,22 @@ The dashboard can trigger a full deployment or an incremental update. Full deployment clones the repository from git and install it as a `.xar` file. With incremental update only the changes to the database collection are applied. +> [!NOTE] +> Tuttle is built to keep track of **data collections** + +> [!NOTE] +> Tuttle is does not run pre- or post install scripts nor change the index configuration on incremental updates! + ### Lets start -1) customize the configuration (`modules/config.xql`) +1) customize the configuration (`data/tuttle.xml`) 2) click on 'full' to trigger a full deployment from git to existdb 3) now you can update your collection with a click on 'incremental' Repositories from which a valid XAR (existing `expath-pkg.xml` and `repo.xml`) package can be generated are installed as a package, all others are created purely on the DB. -**REMARK: Note that there may be index problems if a collection is not installed as a package.** - -**REMARK: Only use it with data collections** +> [!NOTE] +> Note that there may be index problems if a collection is not installed as a package. ## API @@ -243,10 +276,9 @@ be obtained from the respective service. The key for the gitservice must be configured in Gitservice configuration as shown above. +## Roadmap -## DB to Git - -Will be implemented in release 2.0.0 +- [ ] DB to Git ## Honorable mentions: