kevinveenbirkenbach/computer-playbook
1
0
Fork 0
mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2025-08-29 15:06:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

Solved ldap_user nextcloud var import bug (hopefully) and optimized README.md's and metas

Browse Source
This commit is contained in:
Kevin Veen-Birkenbach
2025-03-21 18:01:11 +01:00
parent e4a0473f9e
commit c51f935eff
20 changed files with 352 additions and 257 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
roles/docker-nextcloud/Administration.md
View File

@@ -1,5 +1,7 @@
# Administration
Instructions for manual administrative operations like container login, config file edits, and post-update recovery actions.
## Modify Config 🔧
### Enter the Container
@@ -12,180 +14,3 @@ Inside the container, install a text editor and edit the config:
```bash
apk add --no-cache nano && nano config/config.php
```
---
## Update 🔄
To update the Nextcloud container, execute the following commands on the server:
```bash
docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:mode --on &&
export COMPOSE_HTTP_TIMEOUT=600 &&
export DOCKER_CLIENT_TIMEOUT=600 &&
docker-compose down
```
Afterwards, update the ***applications.nextcloud.version*** variable to the next version and run this repository with this Ansible role.
> **Note:**
> It is only possible to update from one to the next major version at a time.
> Wait for the update to finish.
Verify the update by checking the logs:
```bash
docker-compose logs application
```
and
```bash
docker-compose exec -it application top
```
If Nextcloud remains in maintenance mode after the update, try the following:
```bash
docker exec -it -u www-data nextcloud-application/var/www/html/occ maintenance:mode --on
docker exec -it -u www-data nextcloud-application /var/www/html/occ upgrade
docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:mode --off
```
If the update process fails, execute:
```bash
docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:repair --include-expensive
```
and disable any non-functioning apps.
---
## Recover Latest Backup 💾
```bash
cd {{path_docker_compose_instances}}nextcloud &&
docker-compose down &&
docker-compose exec -i database mysql -u nextcloud -pPASSWORT nextcloud < "/Backups/$(sha256sum /etc/machine-id | head -c 64)/backup-docker-to-local/latest/nextcloud_database/sql/backup.sql" &&
cd {{path_administrator_scripts}}backup-docker-to-local &&
bash ./recover-docker-from-local.sh "nextcloud_data" "$(sha256sum /etc/machine-id | head -c 64)"
```
---
## Database Management 🗄️
### Database Access
To access the database, execute:
```bash
docker-compose exec -it database mysql -u nextcloud -D nextcloud -p
```
### Recreate Database with New Volume
```bash
docker-compose run --detach --name database --env MYSQL_USER="nextcloud" --env MYSQL_PASSWORD=PASSWORD --env MYSQL_ROOT_PASSWORD=PASSWORD --env MYSQL_DATABASE="nextcloud" -v nextcloud_database:/var/lib/mysql
```
---
## OCC (Nextcloud Command Line) 🔧
To use OCC, run:
```bash
docker-compose exec -it -u www-data application /var/www/html/occ
```
### User Administration
#### List Users
```bash
docker compose exec -it -u www-data application php occ user:list
```
#### Sync Users
```bash
docker compose exec -it -u www-data application php occ user:sync
```
#### Create user via CLI
```bash
docker compose exec -it -u www-data application php occ user:add {{username}}
```
#### Make user admin via cli
```bash
docker compose exec -it -u www-data application php occ group:adduser admin {{username}}
```
#### Delete user via CLI
```bash
docker compose exec -it -u www-data application php occ user:delete {{username}}
```
---
### App Administration
```bash
docker compose exec -u www-data application php occ config:list {{app_name}}
```
### Initialize Duplicates
```bash
docker-compose exec -it -u www-data application /var/www/html/occ duplicates:find-all --output
```
### Unlock Files
```bash
docker-compose exec -it -u www-data application /var/www/html/occ maintenance:mode --on
docker-compose exec -it nextcloud_database_1 mysql -u nextcloud -pPASSWORD1234132 -D nextcloud -e "delete from oc_file_locks where 1"
docker-compose exec -it -u www-data application /var/www/html/occ maintenance:mode --off
```
---
## Apps
### App Relevant Tables 🗃️
- `oc_appconfig`
- `oc_migrations`
### Cospend
#### Relevant SQL Commands for Cospend
Debugguging Migrations:
https://github.com/julien-nc/cospend-nc/issues/325
```sql
-- Show all Cospend Tables
SHOW TABLES where Tables_in_nextcloud LIKE "%cospend%";
-- Show Cospend Configuration
SELECT * FROM `oc_appconfig` WHERE appid LIKE "%cospend%";
-- Show Cospend Database Migrations
SELECT * FROM `oc_migrations` WHERE app LIKE "%cospend%";
```
# IAM
IAM(Identity and Access Management) is setup via Keycloak and LDAP.
## OpenID Connect (OIDC) Support 🔐
OIDC is supported in this role—for example, via **Keycloak**. OIDC-specific tasks are included when enabled, allowing integration of external authentication providers seamlessly.
### Verify OIDC Configuration
```bash
docker compose exec -u www-data application /var/www/html/occ config:app:get sociallogin custom_providers
```
## LDAP
More information: https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_auth_ldap.html
## Get all relevant entries except password
```sql
SELECT * FROM `oc_appconfig` WHERE appid LIKE "%ldap%" and configkey != "s01ldap_agent_password";
```
## Update User with LDAP values
```bash
docker compose exec -it -u www-data application php occ ldap:check-user --update {{username}}
```
## Federation
If users are just created via Keycloak and not via LDAP, they have a different username. Due to this reaso concider to use LDAP to guaranty that the username is valid.

26
roles/docker-nextcloud/Applications.md Normal file
View File

@@ -0,0 +1,26 @@
# Nextcloud Applications
Details on specific apps like Cospend, including related SQL queries and debugging tips.
## App Relevant Tables 🗃️
- `oc_appconfig`
- `oc_migrations`
## LDAP
## Cospend
### Relevant SQL Commands for Cospend
Debugguging Migrations:
https://github.com/julien-nc/cospend-nc/issues/325
```sql
-- Show all Cospend Tables
SHOW TABLES where Tables_in_nextcloud LIKE "%cospend%";
-- Show Cospend Configuration
SELECT * FROM `oc_appconfig` WHERE appid LIKE "%cospend%";
-- Show Cospend Database Migrations
SELECT * FROM `oc_migrations` WHERE app LIKE "%cospend%";
```

4
roles/docker-nextcloud/Architecture.md Normal file
View File

@@ -0,0 +1,4 @@
# Administration
## Other Resources
- [Nextcloud Docker Example with Nginx Proxy, MariaDB, and FPM](https://github.com/nextcloud/docker/blob/master/.examples/docker-compose/with-nginx-proxy/mariadb/fpm/docker-compose.yml)

15
roles/docker-nextcloud/Database.md Normal file
View File

@@ -0,0 +1,15 @@
# Database Management (local)
To manage the database if you installed it locally use the following comments. If you have created the database via the central database option, look for the related documentation.
## Database Access
To access the database, execute:
```bash
docker-compose exec -it database mysql -u nextcloud -D nextcloud -p
```
### Recreate Database with New Volume
```bash
docker-compose run --detach --name database --env MYSQL_USER="nextcloud" --env MYSQL_PASSWORD=PASSWORD --env MYSQL_ROOT_PASSWORD=PASSWORD --env MYSQL_DATABASE="nextcloud" -v nextcloud_database:/var/lib/mysql
```

32
roles/docker-nextcloud/IAM.md Normal file
View File

@@ -0,0 +1,32 @@
# Identity and Access Management
IAM(Identity and Access Management) is setup via Keycloak and LDAP.
## OpenID Connect (OIDC) Support 🔐
OIDC is supported in this role—for example, via **Keycloak**. OIDC-specific tasks are included when enabled, allowing integration of external authentication providers seamlessly.
### Verify OIDC Configuration
```bash
docker compose exec -u www-data application /var/www/html/occ config:app:get sociallogin custom_providers
```
## LDAP
More information: https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_auth_ldap.html
## Get all relevant entries except password
```sql
SELECT * FROM `oc_appconfig` WHERE appid LIKE "%ldap%" and configkey != "s01ldap_agent_password";
```
## Update User with LDAP values
```bash
docker compose exec -it -u www-data application php occ ldap:check-user --update {{username}}
```
## Federation
If users are just created via Keycloak and not via LDAP, they have a different username. Due to this reaso concider to use LDAP to guaranty that the username is valid.

55
roles/docker-nextcloud/OCC.md Normal file
View File

@@ -0,0 +1,55 @@
# OCC (Nextcloud Command Line) 🔧
Reference for frequently used OCC commands, including user and app management.
## General Use
To use OCC, run:
```bash
docker-compose exec -it -u www-data application /var/www/html/occ
```
## User Administration
### List Users
```bash
docker compose exec -it -u www-data application php occ user:list
```
### Sync Users
```bash
docker compose exec -it -u www-data application php occ user:sync
```
### Create user via CLI
```bash
docker compose exec -it -u www-data application php occ user:add {{username}}
```
### Make user admin via cli
```bash
docker compose exec -it -u www-data application php occ group:adduser admin {{username}}
```
### Delete user via CLI
```bash
docker compose exec -it -u www-data application php occ user:delete {{username}}
```
---
## App Administration
```bash
docker compose exec -u www-data application php occ config:list {{app_name}}
```
## Initialize Duplicates
```bash
docker-compose exec -it -u www-data application /var/www/html/occ duplicates:find-all --output
```
## Unlock Files
```bash
docker-compose exec -it -u www-data application /var/www/html/occ maintenance:mode --on
docker-compose exec -it nextcloud_database_1 mysql -u nextcloud -pPASSWORD1234132 -D nextcloud -e "delete from oc_file_locks where 1"
docker-compose exec -it -u www-data application /var/www/html/occ maintenance:mode --off
```

57
roles/docker-nextcloud/README.md
View File

@@ -1,24 +1,45 @@
# Nextcloud Server
# Nextcloud
This repository contains an Ansible role for deploying and managing [Nextcloud](https://nextcloud.com/) using [Docker](https://www.docker.com/). It covers configuration modifications, updates, backups, database management, and more. Additionally, OIDC (OpenID Connect) is supported (for example, via **Keycloak**).
---
## Description
## Other Resources
This Ansible role provisions a production-grade **Nextcloud** deployment using Docker Compose. It includes support for LDAP and OIDC authentication, Redis caching, secure configuration management, and declarative plugin control via `occ`. The setup is modular and integrates cleanly into larger infrastructure environments.
- [Nextcloud Docker Example with Nginx Proxy, MariaDB, and FPM](https://github.com/nextcloud/docker/blob/master/.examples/docker-compose/with-nginx-proxy/mariadb/fpm/docker-compose.yml)
- [Nextcloud Upgrade via Docker by Goneuland](https://goneuland.de/nextcloud-upgrade-auf-neue-versionen-mittels-docker/)
- [Nextcloud Data Version Issue](https://help.nextcloud.com/t/cant-start-nextcloud-because-the-version-of-the-data-is-higher-than-the-docker-image-version-and-downgrading-is-not-supported/109438)
- [Nextcloud Docker Issue #1302](https://github.com/nextcloud/docker/issues/1302)
- [Update to Nextcloud 22 Failed Database Error](https://help.nextcloud.com/t/update-to-22-failed-with-database-error-updated/120682)
- [Nextcloud 21.0.0-beta1 Database Error](https://help.nextcloud.com/t/nc-update-to-21-0-0-beta1-exception-database-error/101124/4)
- [Reset Password for MariaDB/MySQL in Docker](https://wolfgang.gassler.org/reset-password-mariadb-mysql-docker/)
- [Ansible Docker Container and depends_on Issue](https://unix.stackexchange.com/questions/478855/ansible-docker/container/and-depends-on)
- [Docker Convenience Scripts by gdiepen](https://github.com/gdiepen/docker-convenience-scripts)
- [Issues After Upgrading to Nextcloud 21](https://help.nextcloud.com/t/several-issues-after-upgrading-to-nextcloud-21/113118/3)
- [Nextcloud Talk Plugin and Turnserver in Docker](https://forum.openmediavault.org/index.php?thread/31782-docker-nextcloud-talk-plugin-and-turnserver/)
- [Nextcloud Talk on Docker: Turn Server Issues](https://help.nextcloud.com/t/nextcloud-talk-im-docker/container/turn-server-auf-docker-host-kein-video/84133/10)
## Overview
---
*Enjoy and happy containerizing! 😄*
The role ensures consistent deployments, full automation, and secure configuration injection into `config.php` using additive includes. Authentication is handled through LDAP and OIDC (e.g., via Keycloak), and backup/recovery operations are fully supported.
## Purpose
To automate the deployment of **secure, extensible, and production-ready Nextcloud instances** using Docker and Ansible.
## Features
- Dockerized Nextcloud (PHP-FPM, Nginx, Cron, Redis)
- Templated Nginx configuration (internal and external)
- Automated certificate and HTTPS proxy integration
- Healthcheck support
- Backup & recovery integration
- IAM & SOO
- Hundreds of integrated plugins
## Related Documentation
Here are all supporting documentation files within this role:
| Topic | Description |
|-------|-------------|
| [Applications](Applications.md) | SQL examples and debug notes for plugins like **Cospend** |
| [Architecture](Architecture.md) | Overview of architectural integrations |
| [Administration](Administration.md) | Manual operations like update, config edits, recovery |
| [Update](Update.md) | Step-by-step update and restore instructions |
| [OCC](OCC.md) | Nextcloud CLI usage guide (user management, config, maintenance) |
| [Database](Database.md) | Managing the database (local mode) |
| [IAM](IAM.md) | LDAP & OIDC Identity and Access Management |
## External Resources
- [Nextcloud Docker Documentation](https://github.com/nextcloud/docker)
- [Nextcloud Admin Manual](https://docs.nextcloud.com/server/latest/admin_manual/)
- [LDAP Integration Guide](https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_auth_ldap.html)
- [OIDC Login Plugin (pulsejet)](https://github.com/pulsejet/nextcloud-oidc-login)
- [Sociallogin Plugin (Official)](https://apps.nextcloud.com/apps/sociallogin)

53
roles/docker-nextcloud/Update.md Normal file
View File

@@ -0,0 +1,53 @@
# Update 🔄
To update the Nextcloud container, execute the following commands on the server:
```bash
docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:mode --on &&
export COMPOSE_HTTP_TIMEOUT=600 &&
export DOCKER_CLIENT_TIMEOUT=600 &&
docker-compose down
```
Afterwards, update the ***applications.nextcloud.version*** variable to the next version and run this repository with this Ansible role.
> **Note:**
> It is only possible to update from one to the next major version at a time.
> Wait for the update to finish.
Verify the update by checking the logs:
```bash
docker-compose logs application
```
and
```bash
docker-compose exec -it application top
```
If Nextcloud remains in maintenance mode after the update, try the following:
```bash
docker exec -it -u www-data nextcloud-application/var/www/html/occ maintenance:mode --on
docker exec -it -u www-data nextcloud-application /var/www/html/occ upgrade
docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:mode --off
```
If the update process fails, execute:
```bash
docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:repair --include-expensive
```
and disable any non-functioning apps.
---
## Recover Latest Backup 💾
```bash
cd {{path_docker_compose_instances}}nextcloud &&
docker-compose down &&
docker-compose exec -i database mysql -u nextcloud -pPASSWORT nextcloud < "/Backups/$(sha256sum /etc/machine-id | head -c 64)/backup-docker-to-local/latest/nextcloud_database/sql/backup.sql" &&
cd {{path_administrator_scripts}}backup-docker-to-local &&
bash ./recover-docker-from-local.sh "nextcloud_data" "$(sha256sum /etc/machine-id | head -c 64)"
```
## Other Resources
- [Nextcloud Upgrade via Docker by Goneuland](https://goneuland.de/nextcloud-upgrade-auf-neue-versionen-mittels-docker/)

30
roles/docker-nextcloud/meta/main.yml Normal file
View File

@@ -0,0 +1,30 @@
---
galaxy_info:
author: "Kevin Veen-Birkenbach"
description: >
Provisions a secure and production-ready Nextcloud instance,
with support for LDAP, OIDC, SSO, and automated plugin configuration.
license: "CyMaIS NonCommercial License (CNCL)"
license_url: "https://s.veen.world/cncl"
company: |
Kevin Veen-Birkenbach
Consulting & Coaching Solutions
https://www.veen.world
min_ansible_version: "2.9"
platforms:
- name: Linux
versions:
- all
galaxy_tags:
- nextcloud
- docker
- nginx
- oidc
- ldap
- automation
- cloud
- web
- php
repository: "https://s.veen.world/cymais"
issue_tracker_url: "https://s.veen.world/cymaisissues"
documentation: "https://s.veen.world/cymais/docker-nextcloud"

0
roles/docker-nextcloud/tasks/plugins/ldap.yml → roles/docker-nextcloud/tasks/plugins/user_ldap.yml
View File

2
roles/docker-nextcloud/vars/README.md Normal file
View File

@@ -0,0 +1,2 @@
# Variables
This folder contains the Nextcloud Variables

2
roles/docker-nextcloud/vars/main.yml
View File

@@ -11,7 +11,7 @@ domain: "{{domains[application_id]}}
http_port: "{{ ports.localhost.http[application_id] }}" # Port at which nextcloud is reachable in the local network
# Localhost
nextcloud_localhost_plugin_configuration_directory: "{{role_path}}/plugins/" # Folder in which the files for the plugin configuration are stored
nextcloud_localhost_plugin_configuration_directory: "{{role_path}}/vars/plugins/" # Folder in which the files for the plugin configuration are stored
# Host

3
roles/docker-nextcloud/vars/plugins/README.md
View File

@@ -1 +1,2 @@
This folder contains the plugin specific configurations which willö be applied
# Plugins
This folder contains the plugin specific configurations which will be applied

0
roles/docker-nextcloud/vars/plugins/ldap.yml → roles/docker-nextcloud/vars/plugins/user_ldap.yml
View File