From 95cffcb008d698489f8f9fb2765f005b5460564c Mon Sep 17 00:00:00 2001 From: Nicole Fernando Date: Tue, 12 Aug 2025 21:23:01 +0800 Subject: [PATCH] Initial commit --- nextcloud-s3-gitea-starter/.gitignore | 25 +++ nextcloud-s3-gitea-starter/LICENSE | 12 ++ nextcloud-s3-gitea-starter/README.md | 164 ++++++++++++++++++ nextcloud-s3-gitea-starter/SECURITY.md | 12 ++ .../docs/ALB_CloudFront.md | 11 ++ .../docs/Issue_CloudFront.md | 6 + .../nextcloud/config.php.example | 16 ++ .../scripts/setup_nextcloud.sh | 20 +++ .../scripts/upgrade_php.sh | 14 ++ 9 files changed, 280 insertions(+) create mode 100644 nextcloud-s3-gitea-starter/.gitignore create mode 100644 nextcloud-s3-gitea-starter/LICENSE create mode 100644 nextcloud-s3-gitea-starter/README.md create mode 100644 nextcloud-s3-gitea-starter/SECURITY.md create mode 100644 nextcloud-s3-gitea-starter/docs/ALB_CloudFront.md create mode 100644 nextcloud-s3-gitea-starter/docs/Issue_CloudFront.md create mode 100644 nextcloud-s3-gitea-starter/nextcloud/config.php.example create mode 100644 nextcloud-s3-gitea-starter/scripts/setup_nextcloud.sh create mode 100644 nextcloud-s3-gitea-starter/scripts/upgrade_php.sh diff --git a/nextcloud-s3-gitea-starter/.gitignore b/nextcloud-s3-gitea-starter/.gitignore new file mode 100644 index 0000000..b677a73 --- /dev/null +++ b/nextcloud-s3-gitea-starter/.gitignore @@ -0,0 +1,25 @@ +# Logs and caches +*.log +cache/ +data/ +tmp/ +*.swp +*.swo + +# Composer / PHP +vendor/ + +# Node (if present) +node_modules/ + +# Env / secrets +.env +*.key +*.pem +*.crt + +# OS / editor +.DS_Store +Thumbs.db +.idea/ +.vscode/ diff --git a/nextcloud-s3-gitea-starter/LICENSE b/nextcloud-s3-gitea-starter/LICENSE new file mode 100644 index 0000000..e130317 --- /dev/null +++ b/nextcloud-s3-gitea-starter/LICENSE @@ -0,0 +1,12 @@ +MIT License + +Copyright (c) 2025 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. diff --git a/nextcloud-s3-gitea-starter/README.md b/nextcloud-s3-gitea-starter/README.md new file mode 100644 index 0000000..a368a9b --- /dev/null +++ b/nextcloud-s3-gitea-starter/README.md @@ -0,0 +1,164 @@ +# Nextcloud on EC2 with S3 Primary Storage + +This repo captures the deployment steps, configs, and operational notes for a Nextcloud server on AWS EC2 with **Amazon S3 as primary storage** and an optional **ALB + CloudFront + ACM** front end. + +> **Important:** This is a sanitized version. Replace placeholders (e.g., `YOUR-BUCKET-NAME`) with your real values. **Never commit secrets** (AWS keys, passwords, access tokens). + +## Architecture (high-level) + +- EC2 (Ubuntu 22.04 LTS) running Apache + PHP + MySQL (or MariaDB) +- Nextcloud application deployed under `/var/www/html/nextcloud` +- S3 bucket used as the primary storage via the `objectstore` config +- Optional: ALB (HTTP/HTTPS) + ACM cert + CloudFront in front of ALB + +## Prerequisites + +- AWS account with permissions to create VPC/subnets (or use existing), EC2, S3, IAM, ACM, ALB, CloudFront, Route 53 records as needed +- A domain (Route 53 hosted zone recommended) +- SSH access to the EC2 instance +- Gitea (or Git) access for storing this repo + +## EC2 Base Setup (condensed) + +1. Launch EC2 (Ubuntu 22.04 LTS; instance size as needed). +2. Update packages: + ```bash + sudo apt update && sudo apt upgrade -y + ``` +3. Install Apache + MySQL: + ```bash + sudo apt-get install -y apache2 mysql-server + sudo systemctl enable --now apache2 mysql + sudo mysql_secure_installation # choose a strong policy + ``` +4. Create DB and user: + ```sql + CREATE DATABASE nextcloud; + CREATE USER 'nextcloud'@'localhost' IDENTIFIED BY 'REPLACE_ME_SECURE_PASSWORD'; + GRANT ALL PRIVILEGES ON nextcloud.* TO 'nextcloud'@'localhost'; + FLUSH PRIVILEGES; + ``` +5. Install PHP and extensions (adjust version as needed): + ```bash + sudo apt-get install -y php libapache2-mod-php php-gd php-json php-mysql php-curl php-mbstring php-intl php-imagick php-xml php-zip php-bcmath php-gmp + ``` +6. Download and place Nextcloud: + ```bash + cd ~ && wget https://download.nextcloud.com/server/releases/latest.zip + sudo apt-get install -y unzip + unzip latest.zip + sudo mv nextcloud /var/www/html/nextcloud + sudo chown -R www-data:www-data /var/www/html/nextcloud + ``` +7. Apache vhost (HTTP example): + ```apache + + ServerName YOUR_PUBLIC_IP_OR_DNS + DocumentRoot /var/www/html/nextcloud + + + Require all granted + Options FollowSymlinks MultiViews + AllowOverride All + + Dav off + + + + ErrorLog ${APACHE_LOG_DIR}/nextcloud.error.log + CustomLog ${APACHE_LOG_DIR}/nextcloud.access.log common + + ``` + Then: + ```bash + sudo a2ensite nextcloud.conf + sudo a2dissite 000-default.conf + sudo a2enmod rewrite + sudo systemctl reload apache2 && sudo systemctl restart apache2 + sudo apachectl -t # check config + ``` + +## Configure S3 as Primary Storage + +Edit `config.php` and add the `objectstore` block (see `nextcloud/config.php.example`): +- Set `bucket`, `region`, `key`, `secret`. Prefer **instance profiles** (IAM roles) over static keys if possible. + +After enabling S3: +```bash +# From the Nextcloud directory +cd /var/www/html/nextcloud +sudo -u www-data php occ files:scan --all +sudo -u www-data php occ maintenance:repair --include-expensive +``` + +## PHP Upgrade (if required) + +If Nextcloud requires a newer PHP (example: upgrade from 8.1 to 8.4 using Ondřej Surý PPA): +```bash +sudo add-apt-repository -y ppa:ondrej/php +sudo apt update +sudo apt install -y php8.4 php8.4-{zip,mbstring,gd,curl,xml,intl,bcmath,mysql} +sudo a2dismod php8.1 && sudo a2enmod php8.4 +sudo systemctl restart apache2 +php -v +``` + +Tune `memory_limit` in `/etc/php/8.4/apache2/php.ini` (e.g., `512M`), and adjust OPcache if needed in `/etc/php/8.4/mods-available/opcache.ini`. + +## ALB + ACM + CloudFront (optional) + +- Request ACM certificates (in `us-east-1` for CloudFront; also in your EC2 region for ALB). +- Create Target Group (HTTP:80) and ALB (listeners 80 and 443 with redirect to HTTPS). +- Attach certificate to HTTPS listener. +- Put CloudFront in front of ALB and forward required headers/methods for Nextcloud. +- Ensure UI elements (file list, upload button) work when accessed via CloudFront; fix behaviors/headers/caching if they disappear. + +See `docs/ALB_CloudFront.md` and `docs/Issue_CloudFront.md` for tips. + +## Troubleshooting Notes + +- `Could not open input file: occ` → run from `/var/www/html/nextcloud` and as `www-data`: + ```bash + cd /var/www/html/nextcloud + sudo -u www-data php occ status + ``` +- After changes, re-run maintenance tasks: + ```bash + sudo -u www-data php occ maintenance:repair + sudo -u www-data php occ files:scan --all + ``` + +## Repo Hygiene + +- Use `.env`/instance roles for secrets; commit **only** `.env.example`. +- Add `.gitignore` for logs, caches, and secrets. +- Use small, meaningful commits (see **Suggested Commit Plan** below). + +## Suggested Commit Plan + +1. `chore: scaffold repo (README, .gitignore)` +2. `docs: base EC2 + Nextcloud install` +3. `feat: add S3 objectstore template` +4. `docs: ALB/ACM/CloudFront notes` +5. `chore: add helper scripts` +6. `docs: troubleshooting + PHP upgrade` +7. `security: add SECURITY.md and redaction guidance` + +--- + +## Quick Start with Gitea + +1. Create a repo in Gitea (e.g., `nextcloud-s3-deploy`). +2. Initialize locally: + ```bash + cd nextcloud-s3-gitea-starter + git init + git add . + git commit -m "chore: scaffold repo from deployment notes" + git branch -M main + git remote add origin https://GITEA_HOST/YOUR_USER/nextcloud-s3-deploy.git + git push -u origin main + ``` +3. Make incremental commits as you refine. + +> If you prefer SSH, set up an SSH key in Gitea and use the SSH URL instead of HTTPS. diff --git a/nextcloud-s3-gitea-starter/SECURITY.md b/nextcloud-s3-gitea-starter/SECURITY.md new file mode 100644 index 0000000..66956c6 --- /dev/null +++ b/nextcloud-s3-gitea-starter/SECURITY.md @@ -0,0 +1,12 @@ +# Security & Secrets Policy + +- **Do not commit secrets**: passwords, AWS access keys, tokens, private keys. +- Use **IAM roles** on EC2 instead of static access keys where possible. +- If you must use static keys locally, store them in `.env` and keep `.env` out of version control. +- Rotate any credentials that were ever pasted into docs or terminals. +- Review commits before pushing (e.g., `git log -p`, `git diff --staged`). + +If a secret was accidentally committed: +1. Rotate/revoke it in the provider immediately. +2. `git filter-repo` or GitHub/Gitea security tools to purge from history. +3. Force-push a corrected history. diff --git a/nextcloud-s3-gitea-starter/docs/ALB_CloudFront.md b/nextcloud-s3-gitea-starter/docs/ALB_CloudFront.md new file mode 100644 index 0000000..902f4bf --- /dev/null +++ b/nextcloud-s3-gitea-starter/docs/ALB_CloudFront.md @@ -0,0 +1,11 @@ +# ALB + ACM + CloudFront Notes + +- Request ACM certs: + - `us-east-1` (for CloudFront) + - Your EC2 region (for ALB HTTPS) +- Target Group: HTTP:80 to your EC2 instance(s). +- ALB: Internet-facing, listeners 80 (redirect to 443) and 443 (with cert). +- CloudFront: Origin = ALB DNS; forward headers/methods required by Nextcloud. +- If UI elements vanish behind CloudFront (file list/upload button): + - Check behaviors, caching, headers, and methods pass-through. + - Bypass CloudFront (hit ALB directly) to isolate the issue. diff --git a/nextcloud-s3-gitea-starter/docs/Issue_CloudFront.md b/nextcloud-s3-gitea-starter/docs/Issue_CloudFront.md new file mode 100644 index 0000000..1c038d6 --- /dev/null +++ b/nextcloud-s3-gitea-starter/docs/Issue_CloudFront.md @@ -0,0 +1,6 @@ +# Issue Log: After switching to ACM + CloudFront + +- Symptom: Previously uploaded files disappeared and upload button missing. +- Bypassing CloudFront (ALB direct) works. +- Likely cause: CloudFront behaviors/headers/methods/caching not aligned with Nextcloud. +- Action: Adjust CloudFront settings and retest. diff --git a/nextcloud-s3-gitea-starter/nextcloud/config.php.example b/nextcloud-s3-gitea-starter/nextcloud/config.php.example new file mode 100644 index 0000000..8dc323a --- /dev/null +++ b/nextcloud-s3-gitea-starter/nextcloud/config.php.example @@ -0,0 +1,16 @@ + array( + 'class' => '\OC\Files\ObjectStore\S3', + 'arguments' => array( + 'bucket' => 'YOUR-BUCKET-NAME', + 'region' => 'YOUR-BUCKET-REGION', + 'key' => 'YOUR_AWS_ACCESS_KEY_ID', + 'secret' => 'YOUR_AWS_SECRET_ACCESS_KEY', + // Optional: + // 'use_ssl' => true, + // 'use_path_style' => false, + // 'hostname' => 's3.YOUR-BUCKET-REGION.amazonaws.com', + ), + ), +); diff --git a/nextcloud-s3-gitea-starter/scripts/setup_nextcloud.sh b/nextcloud-s3-gitea-starter/scripts/setup_nextcloud.sh new file mode 100644 index 0000000..f0f65b3 --- /dev/null +++ b/nextcloud-s3-gitea-starter/scripts/setup_nextcloud.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Basic Nextcloud install helpers (run on Ubuntu 22.04) +sudo apt update && sudo apt upgrade -y +sudo apt-get install -y apache2 mysql-server unzip + +sudo systemctl enable --now apache2 mysql + +# PHP baseline +sudo apt-get install -y php libapache2-mod-php php-gd php-json php-mysql php-curl php-mbstring php-intl php-imagick php-xml php-zip php-bcmath php-gmp + +# Fetch Nextcloud (latest) +cd ~ +wget https://download.nextcloud.com/server/releases/latest.zip +unzip -o latest.zip +sudo mv nextcloud /var/www/html/nextcloud +sudo chown -R www-data:www-data /var/www/html/nextcloud + +echo "Now create DB, configure Apache vhost, and browse to /nextcloud to finish setup." diff --git a/nextcloud-s3-gitea-starter/scripts/upgrade_php.sh b/nextcloud-s3-gitea-starter/scripts/upgrade_php.sh new file mode 100644 index 0000000..e02e0c1 --- /dev/null +++ b/nextcloud-s3-gitea-starter/scripts/upgrade_php.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Upgrade PHP to 8.4 via Ondřej Surý PPA +sudo add-apt-repository -y ppa:ondrej/php +sudo apt update +sudo apt install -y php8.4 php8.4-zip php8.4-mbstring php8.4-gd php8.4-curl php8.4-xml php8.4-intl php8.4-bcmath php8.4-mysql + +# Switch Apache PHP module +sudo a2dismod php8.1 || true +sudo a2enmod php8.4 +sudo systemctl restart apache2 + +echo "Verify with: php -v"