Skip to content

Commit

Permalink
feat(docs): import docs
Browse files Browse the repository at this point in the history
  • Loading branch information
matej21 committed Jun 10, 2024
1 parent abfddb9 commit dbb7026
Show file tree
Hide file tree
Showing 152 changed files with 20,270 additions and 9,765 deletions.
12 changes: 0 additions & 12 deletions docs/blog/2019-05-28-first-blog-post.md

This file was deleted.

44 changes: 0 additions & 44 deletions docs/blog/2019-05-29-long-blog-post.md

This file was deleted.

20 changes: 0 additions & 20 deletions docs/blog/2021-08-01-mdx-blog-post.mdx

This file was deleted.

Binary file not shown.
25 changes: 0 additions & 25 deletions docs/blog/2021-08-26-welcome/index.md

This file was deleted.

17 changes: 0 additions & 17 deletions docs/blog/authors.yml

This file was deleted.

16 changes: 0 additions & 16 deletions docs/blog/tags.yml

This file was deleted.

61 changes: 61 additions & 0 deletions docs/docs/cloud/permissions.md
Original file line number Diff line number Diff line change
@@ -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>
134 changes: 134 additions & 0 deletions docs/docs/guides/acl-definition.md
Original file line number Diff line number Diff line change
@@ -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()
}

```
53 changes: 53 additions & 0 deletions docs/docs/guides/deploy-contember.md
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit dbb7026

Please sign in to comment.