Merge pull request #719 from contember/docs

move docs from contember/docs repo

.github/workflows/ci.yaml

@@ -5,6 +5,8 @@ on:
     branches: ['main']
     tags: ['**']
   pull_request:
+    paths-ignore:
+      - docs/**
   workflow_dispatch:
 
 env:

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/cloud/permissions.md

@@ -0,0 +1,61 @@
+---
+title: Cloud memberships
+---
+
+## Organization Member Roles and Permissions
+
+In the Contember Cloud Selfcare, we provide different roles that you can assign to members within your organization. Each role comes with specific permissions that determine what actions members can perform. It's essential to understand these roles and their associated permissions to effectively manage your organization.
+
+### 1. Roles for the Organization
+
+#### Owner
+
+The **Owner** role is the highest level of authority within the organization. Owners have full control over the organization, including its settings, billing, and member management. There must be at least one Owner in the organization at all times.
+
+#### Admin
+
+The **Admin** role is the second-highest authority in the organization. Admins have broad permissions, enabling them to manage most aspects of the organization, except billing and some specific member-related actions.
+
+#### Billing
+
+The **Billing** role is responsible for managing the organization's billing settings and payment methods. Users with this role can handle billing-related tasks but have limited access to other aspects of the organization.
+
+#### Developer
+
+The **Developer** role is for members involved in project development. They have permissions to create and manage, as well as start and stop project activities. They cannot delete a project. 
+
+#### Guest
+
+The **Guest** role is for providing limited access to external collaborators. Guests have viewing privileges for projects and metrics, but they cannot perform any modifications within the organization.
+
+### 2. Project-Specific Roles
+
+#### Project Developer
+
+The **Project Developer** role is specifically assigned at the project level. Members with this role have permissions to work on a particular project, allowing them to create, manage, and start/stop project activities.
+
+#### Project Guest
+
+Similar to the Project Developer role, the **Project Guest** role is specific to individual projects. Members with this role are granted viewing access to a specific project, without the ability to make any changes.
+
+It's important to note that the Project Developer and Project Guest roles are distinct from the organization-wide roles and are managed separately for each project.
+
+### Permissions matrix
+
+<div class="acl-table">
+
+|                               | Owner | Admin | Billing | Developer | Guest | Project Developer | Project Guest |
+|-------------------------------|--------------------------------|--------------------------------|--------------------------------|--------------------------------|--------------------------------|--------------------------------|--------------------------------|
+| View projects                 | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> |
+| View metrics                  | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> |
+| View members                  | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+| Manage owner / billing member | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+| Manage other members          | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+| Create projects               | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+| Start / stop project          | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  |
+| Edit project settings         | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  |
+| Delete project                | <span class="acl-y">YES</span> | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+| View billing                  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+| Manage billing                | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-y">YES</span> | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  | <span class="acl-n">NO</span>  |
+
+</div>

docs/docs/guides/acl-definition.md

@@ -0,0 +1,134 @@
+---
+title: Roles and ACL definition
+description: How to write custom roles definition.
+---
+
+Let's say we are defining two roles: a public role, which can see all visible comments, and a moderator role, who can edit and hide comments of given article in assigned category.
+
+A simplified model definition for this example will look like this:
+
+```typescript
+export class Category {
+	// ....
+}
+
+export class Article {
+	category = def.manyHasOne(Category)
+	// ....
+}
+
+export class Comment {
+	article = def.manyHasOne(Article)
+	content = def.stringColumn()
+	hiddenAt = def.dateTimeColumn()
+}
+```
+
+> We are using high level ACL definition API. For some cases, you might prefer a [low level definition API](/reference/engine/schema/acl.md#low-level-definition)
+
+### Public role definition
+
+First, we create a public role using [createRole](/reference/engine/schema/acl.md#create-role) function.
+
+There is only single mandatory argument - a role identifier. In second argument, we can define various role options, as described [here](/reference/engine/schema/acl.md#create-role). 
+
+```typescript
+import { AclDefinition as acl } from '@contember/schema-definition'
+
+export const publicRole = acl.createRole('public') 
+```
+
+Second, we assign an access rule to a `Comment` entity using [allow](/reference/engine/schema/acl.md#allow) function.
+
+In a first argument of the function we pass previously defined role. Second argument is an object with the access definition itself.
+In `when` we define a predicate. In `read` there is an array of accessible fields. You can also use `true` instead of an array to make all fields accessible:
+
+```typescript
+// highlight-start
+@acl.allow(publicRole, {
+	read: ['content'],
+	when: { hiddenAt: { isNull: true } },
+})
+// highlight-end
+export class Comment {
+	// ...
+}
+```
+
+That's all. Now, if you access the API with `public` role, you can see not hidden `Comment` rows, and you can access its `content` field.
+
+### Moderator role definition
+
+Now, we define a second mentioned role - a `moderator`. Again, we define a role:
+
+```typescript
+export const moderatorRole = acl.createRole('moderator')
+```
+
+Now it gets a bit more tricky, as we want to allow to only moderate comments in given category.
+
+Let's define an [entity variable](#entity-variable), where a category ID (or a list of categories) will be stored for given user.
+
+```typescript
+export const categoryIdVariable = acl.createEntityVariable('categoryId', 'Category', moderatorRole)
+```
+
+You can manage this variable [on memberships using Tenant API](/reference/engine/tenant/memberships.md) using its name - `categoryId`.
+
+Now we attach another ACL definition to our `Comment` entity:
+
+```typescript
+// highlight-start
+@acl.allow(moderatorRole, {
+	update: ['hiddenAt', 'content'],
+	when: { article: { category: { id: categoryIdVariable } } },
+})
+// highlight-end
+// other ACL definitions
+export class Comment {
+	// ...
+}
+```
+
+As you can see, you can traverse through relations. Our definition says, that `moderator` can update fields `hiddenAt` and `content` of any `Comment` of an `Article` in a `Category` defined in `categoryId` variable. 
+
+:::note migrations
+Don't forget to [create a migration](/reference/engine/migrations/basics.md) to apply changes:
+```bash
+npm run contember migrations:diff my-blog setup-acl
+```
+:::
+
+#### Full example:
+```typescript
+import { SchemaDefinition as def, Acldefinition as acl } from '@contember/schema-definition'
+
+export const publicRole = acl.createRole('public')
+
+export const moderatorRole = acl.createRole('moderator')
+export const categoryIdVariable = acl.createEntityVariable('categoryId', 'Category', moderatorRole)
+
+export class Category {
+	// ....
+}
+
+export class Article {
+	category = def.manyHasOne(Category)
+	// ....
+}
+
+@acl.allow(moderatorRole, {
+	when: { article: { category: { id: categoryIdVariable } } },
+	update: ['hiddenAt', 'content'],
+})
+@acl.allow(publicRole, {
+	when: { hiddenAt: { isNull: true } },
+	read: ['content'],
+})
+export class Comment {
+	article = def.manyHasOne(Article)
+	content = def.stringColumn()
+	hiddenAt = def.dateTimeColumn()
+}
+
+```

docs/docs/guides/deploy-contember.md

@@ -0,0 +1,53 @@
+---
+title: Deploy to Contember Cloud
+description: From local project to production in 15 minutes.
+---
+
+This guide will take you through the deployment of Contember from your local machine to the Contember Cloud.
+
+## Before you start
+
+You should have a project on your machine - complete [quickstart tutorial](/intro/quickstart.mdx) or use one of our ready-made [starter-kits](https://github.com/contember/starter-kits).
+
+## 1. Setup project in Contember Cloud
+
+Go to https://contember.cloud and create an account if you don't have one. After sign up create your first project. Choose a unique name for it.
+
+![Contember Cloud: create project](/assets/cloud-create-project-v2.png)
+
+You should receive an email with a link to sign into administration. You don't need it right now - we will come back to it.
+
+
+On your project's page in Contember Cloud console click on "Deploy token" to create a deploy command with your deploy secret token.
+
+![Contember Cloud: project detail](/assets/cloud-project-detail-v2.png)
+
+It will look something like this:
+
+```bash
+npm run deploy contember://example:4faef77592845fbeaf390c5e86989b1ea493e5d0@example.eu.contember.cloud
+```
+
+## 2. Deploy
+
+Copy it and run this command in your project's directory. It will build your project, package the assets and prompt you to confirm details - type `y` (for "yes") to continue. We will apply your project's schema and copy the administration's assets.
+
+```
+$ npm run deploy contember://example:4faef77592845fbeaf390c5e86989b1ea493e5d0@example.eu.contember.cloud
+...
+Deployment successful
+```
+
+## 3. Sign in to the administration
+
+When you created the project, you received an email with a link to create an administration account. This account is separate from your Contember Cloud console account.
+
+## Next steps
+
+You can change your local project however you like, it's completely independent from the deployed version. After you make any changes in the project's code, test it locally and are ready to deploy it, build it and deploy it again as we did in steps two and three.
+
+You can also setup [deployment from GitHub Actions](./deploy-github-actions).
+
+## Troubleshooting
+
+If you encounter a problem, feel free to open [an issue on GitHub](https://github.com/contember/admin/issues/new). Don't forget to attach screenshots and terminal output.

docs/docs/guides/deploy-github-actions.md

@@ -0,0 +1,60 @@
+---
+title: Deploy using GitHub Actions
+description: Automate your Contember Cloud deployment.
+---
+
+This guide will take you through the deployment of Contember from your GitHub repository to the Contember Cloud.
+
+## Before you start
+
+You should have a project in a GitHub repository - complete [quickstart tutorial](/intro/quickstart.mdx) or use one of our ready-made [starter-kits](https://github.com/contember/starter-kits).
+
+
+Setup automatic deployment to Contember Cloud after push to GitHub using GitHub Actions.
+
+## 1. Create Contember DSN
+
+You need to get Contember DSN which specifies which project to deploy to and includes secret token. In Contember Cloud console on your project's page click a "Create new deploy token" button. You will get a deploy command, but we will need only the part after the `deploy` word - starting with `contember://`. It should look like this:
+
+```txt title="Contember DSN example"
+contember://example:4faef77592845fbeaf390c5e86989b1ea493e5d0@example.eu.contember.cloud
+```
+
+## 2. Create repository secret
+
+On GitHub go to your repository settings and select Security → Secrets → Actions. Click on "New repository secret" button, name your new secret `CONTEMBER_DEPLOY_DSN` and input the Contember DSN you got from Cloud Console.
+
+![GitHub actions create secret screen](/assets/github-actions-secret.png)
+
+
+## 3. Commit workflow file
+
+After you created the repository secret, you can create a workflow that will run after each push to `main` branch. Create file `.github/workflows/deploy.yml` with following contents.
+
+```yaml title=".github/workflows/deploy.yml"
+name: Deploy
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Build and deploy Contember to production
+      run: npm run deploy ${{ secrets.CONTEMBER_DEPLOY_DSN }} -- --yes
+```
+
+Now, when you push to `main` branch, your code should be automatically deployed to Contember Cloud.
+
+## Troubleshooting
+
+If you encounter a problem, feel free to open [an issue on GitHub](https://github.com/contember/admin/issues/new) or ask us in [our Discord server](https://discord.gg/EkhsuAK2Fg). Don't forget to attach screenshots and terminal output.