## 1. Project Overview & Quickstart (opencloud-eu/opencloud)

[](https://ci.opencloud.rocks/repos/3)
 [](https://app.element.io/#/room/#opencloud:matrix.org)
 [](https://opensource.org/licenses/Apache-2.0)

# Server Backend


> [!TIP]
> For general information about OpenCloud and how to install please visit [OpenCloud on Github](https://github.com/opencloud-eu/) and [OpenCloud GmbH](https://opencloud.eu).

This is the main repository of the OpenCloud server.
It contains the golang codebase for the backend services.

## Getting Involved

The OpenCloud server is released under [Apache 2.0](https://github.com/opencloud-eu/opencloud/blob/main/LICENSE).
The project is thrilled to receive contributions in all forms.
Start hacking now, there are many ways to get involved such as:

- Reporting [issues or bugs](https://github.com/opencloud-eu/opencloud/issues)
- Requesting [features](https://github.com/opencloud-eu/opencloud/issues)
- [Writing documentation](https://github.com/opencloud-eu/docs)
- [Writing code or extend our tests](https://github.com/opencloud-eu/opencloud/pulls)
- [Reviewing code](https://github.com/opencloud-eu/opencloud/pulls)
- Helping others in the [community](https://app.element.io/#/room/#opencloud:matrix.org)

Every contribution is meaningful and appreciated!
Please refer to our [Contribution Guidelines](https://github.com/opencloud-eu/opencloud/blob/main/CONTRIBUTING.md) if you want to get started.

## Build OpenCloud

To build the backend, follow these instructions:

Generate the assets needed by e.g., the web UI and the builtin IDP

``` console
make generate
```

Then compile the `opencloud` binary

``` console
make -C opencloud build
```
That will produce the binary `opencloud/bin/opencloud`. It can be started as a local test instance right away with a two step command:

```bash
opencloud/bin/opencloud init && opencloud/bin/opencloud server
```
This creates a server configuration (by default in `$HOME/.opencloud`) and starts the server.

For more setup- and installation options consult the [Development Documentation](https://docs.opencloud.eu/).

## Technology

Important information for contributors about the technology in use.

### Authentication

The OpenCloud backend authenticates users via [OpenID Connect](https://openid.net/connect/) using either an external IdP like [Keycloak](https://www.keycloak.org/) or the embedded [LibreGraph Connect](https://github.com/libregraph/lico) identity provider.

### Database

The OpenCloud backend does not use a database. It stores all data in the filesystem. By default, the root directory of the backend is `$HOME/.opencloud/`.

## Security

If you find a security-related issue, please contact [security@opencloud.eu](mailto:security@opencloud.eu) immediately.

## 2. Official Technical Reference & Guides (opencloud-eu/docs)

# 🌐 Website

This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.


## Installation

```bash
pnpm install
```


## Local Development

Clone this repository and start the local dev server:

```bash
pnpm start
```

This command will launch a local development server and open the site in your browser. Changes are hot-reloaded automatically.

> ⚠️ `docs` tree contains redirects, because some documentation files may have been removed or moved, and old bookmarks should still work. To have those working in the local dev server, the documentation needs to be built first:

```bash
pnpm build
pnpm run serve
```

### Start docs in German

To launch the documentation in German, run:

```bash
pnpm run start --locale de
```

> ⚠️ Switching languages via the language switcher is currently not supported.


## Build

```bash
pnpm build
```

This command generates static content in the `build` folder. You can serve it using any static file hosting service.


## Deployment

### Using SSH:

```bash
USE_SSH=true pnpm deploy
```

### Without SSH:

```bash
GIT_USER=<Your GitHub username> pnpm deploy
```

If you're using GitHub Pages, this will push the production build to the `gh-pages` branch.


## Screenshot Guidelines

| Component        | Width  |
|:----------------|:------:|
| Full screen      | 1920px |
| Menu             | 400px  |
| Pop-up / Modal   | 500px  |

> Highlight key elements in the screenshot with red borders or boxes if needed.

### Example

To include a screenshot in your documentation, use the following format:

```jsx

```

- Use `require(...)` for image paths so they are bundled correctly by Docusaurus
- Always include a meaningful `alt` text to improve accessibility and SEO


## Markdown Guidelines

To maintain a consistent structure across all docs, follow these formatting conventions:

### Frontmatter Example

All `.md` files must begin with a valid frontmatter block:

```yaml
---
id: getting-started
title: Getting Started
sidebar_position: 1
---
```

- `id` must be unique and match the filename (without `.md`)
- `sidebar_position` defines the ordering in the sidebar
- `description` is required to ensure consistent SEO metadata and link previews. Always include a meaningful and concise description.

### Heading Hierarchy

Use the correct heading levels:

```markdown
# Page Title

## Section Heading

### Subsection Heading

#### Optional Sub-subsection
```

> Do not skip heading levels (e.g., don’t go from `##` directly to `####`).


### Info Blocks

Use Docusaurus-style info blocks to highlight important content:

```markdown
:::tip
Helpful tip content goes here.
:::

:::info
General information goes here.
:::

:::warning
Warnings go here.
:::

:::danger
Critical notices go here.
:::
```

### Lists and Steps

Use regular markdown for ordered lists. Do **not** nest deeply.

```markdown
1. First step
2. Second step
3. Third step
```

## Format Before Pushing

Before committing changes, ensure proper formatting using:

```bash
pnpm format:write
pnpm lint:md:fix
```

These commands will:

- Format all project files
- Lint and auto-fix markdown formatting
- Ensure consistent style across documentation

Thanks for helping us keep the docs clean, professional, and easy to read!