+
+
+
+A Google Drive Interface for your Cloudflare R2 Buckets!
-- This project is deployed/self-hosted in your own Cloudflare Account as a Worker, and no credential/token is required to - start using it. +
---- +- ¡Una interfaz tipo Google Drive para tus Buckets de Cloudflare R2! -
- -- Este proyecto se implementa/autohospeda en tu propia cuenta de Cloudflare como un Worker, y no se requiere ninguna credencial/token para comenzar a usarlo. -
- ---- - -**Documentación**: https://r2explorer.dev - -**Demo en Vivo**: https://demo.r2explorer.dev - ---- - -## Características - -- [Explorador de Correo Electrónico](https://r2explorer.dev/guides/setup-email-explorer/) (usando Cloudflare Email Routing) -- [Autenticación Básica](https://r2explorer.dev/getting-started/security/#basic-auth) -- [Autenticación de Acceso de Cloudflare](https://r2explorer.dev/getting-started/security/) -- Navegación muy rápida de bucket/carpeta -- Vista previa en el navegador de pdf, imágenes, txt, markdown, csv, etc. -- Carga mediante arrastrar y soltar (Drag-and-Drop) -- Cargas de múltiples archivos y carpetas -- Crear carpetas -- Cargar/Renombrar/Descargar/Eliminar archivos -- Clic derecho en un archivo para opciones adicionales -- Carga multipart para archivos grandes - -## Primeros pasos - -Ejecuta este comando para configurar un proyecto de ejemplo - -```bash -npm create cloudflare@latest r2-explorer -- --template "G4brym/R2-Explorer/template" -``` - -## Actualizar tu instalación - -Para actualizar a la última versión, solo necesitas instalar el paquete r2-explorer más reciente desde npm y volver a implementar tu aplicación - -```bash -npm install r2-explorer@latest --save -``` - -```bash -wrangler publish -``` - -## Tareas pendientes - -- Permitir nombres de buckets con espacios -- Buscar archivos -- Renombrar carpetas -- Eliminar carpetas -- Miniaturas de imágenes usando workers de Cloudflare -- Información sobre herramientas al pasar el ratón por encima de un archivo con el formato "hace x días" -- Agrupar íconos de bootstrap en lugar de importarlos diff --git a/READMEfr.md b/READMEfr.md deleted file mode 100644 index ab6d438..0000000 --- a/READMEfr.md +++ /dev/null @@ -1,65 +0,0 @@ -[](https://github.com/G4brym/R2-Explorer/commits/main) [](https://github.com/G4brym/R2-Explorer/issues) [](LICENSE) - -Lisez ceci dans d'autres langues : [English](README.md), [Español](READMEes.md), [Português](READMEpt.md) - -# R2-Explorer - -- Une interface Google Drive pour vos compartiments Cloudflare R2 ! -
- -- Ce projet est déployé/auto-hébergé dans votre propre compte Cloudflare en tant que Worker, et aucun identifiant/token n'est requis pour commencer à l'utiliser. -
- ---- - -**Documentation** : https://r2explorer.dev - -**Démo en direct** : https://demo.r2explorer.dev - ---- - -## Fonctionnalités - -- [Explorateur d'e-mails](https://r2explorer.dev/guides/setup-email-explorer/) (utilisant le routage des e-mails Cloudflare) -- [Authentification de base](https://r2explorer.dev/getting-started/security/#basic-auth) -- [Authentification Cloudflare Access](https://r2explorer.dev/getting-started/security/) -- Navigation très rapide dans les compartiments/dossiers -- Aperçu dans le navigateur de fichiers PDF, images, texte, markdown, CSV, etc. -- Téléchargement par glisser-déposer -- Téléchargement de fichiers et de dossiers multiples -- Création de dossiers -- Téléchargement/Renommer/Téléchargement/Suppression de fichiers -- Clic droit sur un fichier pour des options supplémentaires -- Téléchargement multipart pour les gros fichiers - -## Pour commencer - -Exécutez cette commande pour configurer un projet exemple - -```bash -npm create cloudflare@latest r2-explorer -- --template "G4brym/R2-Explorer/template" -``` - -## Mise à jour de votre installation - -Pour mettre à jour vers la dernière version, il vous suffit d'installer le dernier package r2-explorer depuis npm et de redéployer votre application - -```bash -npm install r2-explorer@latest --save -``` - -```bash -wrangler publish -``` - -## À FAIRE - -- Autoriser les noms de compartiments avec des espaces -- Rechercher des fichiers -- Renommer des dossiers -- Supprimer des dossiers -- Miniatures d'images avec les travailleurs Cloudflare -- Info-bulle lors du survol d'un fichier avec le format "il y a x jours" -- Regrouper les icônes Bootstrap au lieu de les importer diff --git a/READMEpt.md b/READMEpt.md deleted file mode 100644 index df95ae0..0000000 --- a/READMEpt.md +++ /dev/null @@ -1,64 +0,0 @@ -[](https://github.com/G4brym/R2-Explorer/commits/main) [](https://github.com/G4brym/R2-Explorer/issues) [](LICENSE) - -Leia isso em outros idiomas: [English](README.md), [Español](READMEes.md), [Français](READMEfr.md) - -# R2-Explorer - -- Uma interface tipo Google Drive para seus Buckets do Cloudflare R2! -
- -- Este projeto é implantado/auto-hospedado em sua própria conta do Cloudflare como um Worker, e não são necessárias credenciais ou tokens para começar a usá-lo. -
- ---- - -**Documentação**: [https://r2explorer.dev](https://r2explorer.dev) - -**Demonstração ao Vivo**: [https://demo.r2explorer.dev](https://demo.r2explorer.dev) - ---- - -## Recursos - -- [Explorador de E-mail](https://r2explorer.dev/guides/setup-email-explorer/) (usando o Roteamento de E-mail do Cloudflare) -- [Autenticação Básica](https://r2explorer.dev/getting-started/security/#basic-auth) -- [Autenticação de Acesso do Cloudflare](https://r2explorer.dev/getting-started/security/) -- Navegação rápida de buckets/pastas -- Visualização no navegador de pdf, imagens, txt, markdown, csv, etc. -- Arraste e solte para carregar (Drag-and-Drop) -- Carregamento de múltiplos arquivos e pastas -- Criar pastas -- Carregar/Renomear/Download/Excluir arquivos -- Clique com o botão direito do mouse em um arquivo para opções adicionais -- Carregamento multipart para arquivos grandes - -## Primeiros passos - -Execute este comando para configurar um projeto de exemplo - -```bash -npm create cloudflare@latest r2-explorer -- --template "G4brym/R2-Explorer/template" -``` - -## Atualizar sua instalação - -Para atualizar para a versão mais recente, você só precisa instalar o pacote r2-explorer mais recente do npm e reimplantar sua aplicação - -```bash -npm install r2-explorer@latest --save -``` - -```bash -wrangler publish -``` - -## Tarefas pendentes -- Permitir nomes de buckets com espaços -- Procurar arquivos -- Renomear pastas -- Excluir pastas -- Miniaturas de imagens usando workers do Cloudflare -- Informações de ferramentas ao passar o mouse sobre um arquivo no formato "há x dias" -- Agrupar ícones do Bootstrap em vez de importá-los diff --git a/docs/_redirects b/docs/_redirects new file mode 100644 index 0000000..4e77009 --- /dev/null +++ b/docs/_redirects @@ -0,0 +1,4 @@ +/getting-started /getting-started/creating-a-new-project 302 +/getting-started/ /getting-started/creating-a-new-project 302 +/getting-started/setup-using-github-actions /getting-started/creating-a-new-project 302 +/getting-started/setup-using-github-actions/ /getting-started/creating-a-new-project 302 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..26fe1d1 --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,90 @@ +site_name: R2 Explorer +site_description: A Google Drive Interface for your Cloudflare R2 Buckets +site_url: https://r2explorer.dev/ +docs_dir: pages +theme: + name: material +# custom_dir: .overrides + logo: assets/logo.svg + favicon: assets/logo.svg + font: + text: Source Sans 3 + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: green + accent: orange + toggle: + icon: material/weather-night + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: green + accent: orange + toggle: + icon: material/weather-sunny + name: Switch to light mode + features: + - search.suggest + - search.highlight + - content.tabs.link + - content.tooltips + - navigation.indexes + - navigation.tabs + - navigation.path + - content.code.annotate + - content.code.copy + - content.code.select + language: en +repo_name: G4brym/R2-Explorer +repo_url: https://github.com/G4brym/R2-Explorer +edit_uri: '' +plugins: + - search +# - social + - termynal + - markdownextradata: + data: data +nav: + - index.md + - Getting started: + - getting-started/creating-a-new-project.md + - getting-started/add-r2-buckets.md + - getting-started/configuration.md + - getting-started/security.md + - getting-started/deploying.md + - getting-started/updating-your-project.md + - guides/setup-email-explorer.md + - guides/migrating-to-1.0.md + - guides/migrating-to-1.1.md + - guides/continue-using-legacy-dashboard.md + - Email explorer: https://r2explorer.dev/guides/setup-email-explorer/ + - Live demo: https://demo.r2explorer.dev/ +markdown_extensions: + - attr_list + - toc: + permalink: true + - markdown.extensions.codehilite: + guess_lang: false + - mdx_include: + base_path: pages + - admonition + - codehilite + - extra + - md_in_html + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format '' + - pymdownx.tabbed + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences diff --git a/docs/pages/assets/cloudflare-access.png b/docs/pages/assets/cloudflare-access.png new file mode 100644 index 0000000..1db7296 Binary files /dev/null and b/docs/pages/assets/cloudflare-access.png differ diff --git a/docs/pages/assets/custom-domain.png b/docs/pages/assets/custom-domain.png new file mode 100644 index 0000000..12ca382 Binary files /dev/null and b/docs/pages/assets/custom-domain.png differ diff --git a/docs/pages/assets/github-action/add-cf-token.png b/docs/pages/assets/github-action/add-cf-token.png new file mode 100644 index 0000000..897a6eb Binary files /dev/null and b/docs/pages/assets/github-action/add-cf-token.png differ diff --git a/docs/pages/assets/github-action/add-variables.png b/docs/pages/assets/github-action/add-variables.png new file mode 100644 index 0000000..0ed9fee Binary files /dev/null and b/docs/pages/assets/github-action/add-variables.png differ diff --git a/docs/pages/assets/github-action/enable-actions.png b/docs/pages/assets/github-action/enable-actions.png new file mode 100644 index 0000000..9bd74b4 Binary files /dev/null and b/docs/pages/assets/github-action/enable-actions.png differ diff --git a/docs/pages/assets/github-action/fork.png b/docs/pages/assets/github-action/fork.png new file mode 100644 index 0000000..db83661 Binary files /dev/null and b/docs/pages/assets/github-action/fork.png differ diff --git a/docs/pages/assets/github-action/new-secret.png b/docs/pages/assets/github-action/new-secret.png new file mode 100644 index 0000000..28d8e29 Binary files /dev/null and b/docs/pages/assets/github-action/new-secret.png differ diff --git a/docs/pages/assets/github-action/trigger-update.png b/docs/pages/assets/github-action/trigger-update.png new file mode 100644 index 0000000..c7ab498 Binary files /dev/null and b/docs/pages/assets/github-action/trigger-update.png differ diff --git a/docs/pages/assets/github-action/update-available.png b/docs/pages/assets/github-action/update-available.png new file mode 100644 index 0000000..cdbcaa9 Binary files /dev/null and b/docs/pages/assets/github-action/update-available.png differ diff --git a/docs/pages/assets/logo.svg b/docs/pages/assets/logo.svg new file mode 100644 index 0000000..80ebe65 --- /dev/null +++ b/docs/pages/assets/logo.svg @@ -0,0 +1,5 @@ + diff --git a/docs/pages/assets/r2-explorer-logo.png b/docs/pages/assets/r2-explorer-logo.png new file mode 100644 index 0000000..c9731e3 Binary files /dev/null and b/docs/pages/assets/r2-explorer-logo.png differ diff --git a/docs/pages/assets/setup-email-routing-2.png b/docs/pages/assets/setup-email-routing-2.png new file mode 100644 index 0000000..2c099f5 Binary files /dev/null and b/docs/pages/assets/setup-email-routing-2.png differ diff --git a/docs/pages/assets/setup-email-routing-3.png b/docs/pages/assets/setup-email-routing-3.png new file mode 100644 index 0000000..d861e10 Binary files /dev/null and b/docs/pages/assets/setup-email-routing-3.png differ diff --git a/docs/pages/assets/setup-email-routing-4.png b/docs/pages/assets/setup-email-routing-4.png new file mode 100644 index 0000000..51c913e Binary files /dev/null and b/docs/pages/assets/setup-email-routing-4.png differ diff --git a/docs/pages/assets/setup-email-routing.png b/docs/pages/assets/setup-email-routing.png new file mode 100644 index 0000000..4c75680 Binary files /dev/null and b/docs/pages/assets/setup-email-routing.png differ diff --git a/docs/pages/assets/update-available.png b/docs/pages/assets/update-available.png new file mode 100644 index 0000000..c628dd1 Binary files /dev/null and b/docs/pages/assets/update-available.png differ diff --git a/docs/pages/getting-started/add-r2-buckets.md b/docs/pages/getting-started/add-r2-buckets.md new file mode 100644 index 0000000..17094dc --- /dev/null +++ b/docs/pages/getting-started/add-r2-buckets.md @@ -0,0 +1,36 @@ +# Add R2 buckets + +The R2 Explorer will only be able to access the buckets you give it access to. + +After creating the buckets you want in the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/r2/overview). + +Update your `wrangler.toml` file, and add the binding for all the buckets you want to access. In this example i'm +adding 2 buckets to my application called `personal-files` and `server-backups`: + +```ts title="wrangler.toml" +name = "my-r2-explorer" +main = "src/index.ts" +compatibility_date = "2023-05-12" + +[[r2_buckets]] +binding = 'personal-files' +bucket_name = 'personal-files' +preview_bucket_name = 'personal-files' + +[[r2_buckets]] +binding = 'server-backups' +bucket_name = 'jfk-server-backups' +preview_bucket_name = 'jfk-server-backups' +``` + +After this, just deploy your application normally with: + +```bash +wrangler deploy +``` + +!!! note + + Notice that you can customize the `binding` name to be whatever you would like and that name is used inside the + dashboard to access the bucket. + diff --git a/docs/pages/getting-started/configuration.md b/docs/pages/getting-started/configuration.md new file mode 100644 index 0000000..8afa30c --- /dev/null +++ b/docs/pages/getting-started/configuration.md @@ -0,0 +1,69 @@ +All customizations are applied in the `src/index.ts` file. + +Here is all the available options: + +| Name | Type(s) | Description | Examples | +|--------------------|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| +| `readonly` | `boolean` or `undefined` | Controls the write access globally, default: `true` | `true` | +| `cors` | `boolean` or `undefined` | Enables or disables CORS access to the internal API, default: `false` | `true` | +| `cfAccessTeamName` | `string` or `undefined` | When set enforces Cloudflare Access in all requests | `radar` (taken from https://radar.cloudflareaccess.com/) | +| `dashboardUrl` | `string` or `undefined` | Allows you to serve a custom dashboard, read more [here](/guides/migrating-to-1.0/#why-is-the-dashboard-no-longer-bundled-in-the-worker) | `https://demo.r2explorer.dev` | +| `emailRouting` | `object` or `undefined` | Customize Email Explorer, read more [here](/guides/setup-email-explorer) | `https://demo.r2explorer.dev` | +| `cacheAssets` | `boolean` or `undefined` | Cache dashboard assets by 5 minutes, default: `true` | `https://demo.r2explorer.dev` | + +`emailRouting` options: + +| Name | Type(s) | Description | Examples | +|----------------|--------------------------|------------------------------------------|--------------------------------------------------------| +| `targetBucket` | `string` or `undefined` | Bucket name that will receive the emails | `my-emails` (assuming my-emails is a real bucket name) | + +## Disabling readonly mode + +For security reasons, by default your application will be in read only mode, to disable this, just update your +`src/index.ts` file, like this: + +```ts title="src/index.ts" +import {R2Explorer} from 'r2-explorer'; + +export default R2Explorer({readonly: false}); +``` + +After this, just deploy your application normally with: + +```bash +wrangler deploy +``` + +!!! danger + + Disabling read only mode, allows **anyone** to upload and change your bucket! + + It is highly recommended to enable authentication in your application, read more [here](./security.md) + +## Setup Custom Domain + +To setup a custom domain, just open the [Cloudflare dashboard](https://dash.cloudflare.com/?to=/:account/workers/services/view/:worker/production/settings#domains) and go to Workers & Pages -> +your worker -> Triggers. And click "Add Custom Domain". + + + +## Configuring Email Explorer target bucket + +By default emails will go to the 1º bucket configured in your `wrangler.toml` file, but you can overwrite it +in the `index.ts` file, like: + +```ts title="src/index.ts" +import {R2Explorer} from 'r2-explorer'; + +export default R2Explorer({ + readonly: false, emailRouting: { + targetBucket: 'my-email-bucket' + } +}); +``` + +After this, just deploy your application normally with: + +```bash +wrangler deploy +``` diff --git a/docs/pages/getting-started/creating-a-new-project.md b/docs/pages/getting-started/creating-a-new-project.md new file mode 100644 index 0000000..6de7d0b --- /dev/null +++ b/docs/pages/getting-started/creating-a-new-project.md @@ -0,0 +1,69 @@ +## 1st Method (Github Action - Recommended) + +Start by creating a new fork of the [github repository here](https://github.com/G4brym/R2-Explorer/fork). + + + +Create a new API Token as described in the [official Cloudflare Docs](https://developers.cloudflare.com/workers/wrangler/migration/v1-to-v2/wrangler-legacy/authentication/#api-token). + +Then, in your new repository go to Settings -> Secret and variables -> Actions -> New repository secret. + + + +Create a new secret with the name `CF_API_TOKEN` and the value as the newly created token. + + + +Now switch to the variables tab and create the following variables: + +- `R2EXPLORER_WORKER_NAME` this is the worker named used to identify the worker in your Cloudflare account. +- `R2EXPLORER_CONFIG` object with the R2-explorer configuration, [read more here](./configuration.md). +- `R2EXPLORER_BUCKETS` buckets in the format `{r2-explorer name}:{bucket name}`, define one bucket per line. +- `R2EXPLORER_DOMAIN` **optional** domain name used to serve the R2-explorer instance, when not set, you will be given a workers.dev domain. + + +Example variables: + +- `R2EXPLORER_WORKER_NAME => my-r2-explorer` +- `R2EXPLORER_CONFIG => { readonly: true }` +- `R2EXPLORER_BUCKETS => example-1:r2-explorer-example-1` +- `R2EXPLORER_DOMAIN => my-domain.com` + + + + + +Now go to the github repository and click Actions -> I understand my workflows, go ahead and enable them. + + + + +After enabling actions, go ahead and trigger a new deploy, you can use this flow at any time to re-deploy +your application. + +Click Actions -> Deploy -> Run workflow -> Run workflow. + + + + +## 2nd Method (create-cloudflare) + +Creating your own instance of R2 Explorer is easy, after making sure you have [Node](https://nodejs.org) installed, +run this tool that will help you get started: + +```bash +npm create cloudflare@latest r2-explorer -- --template "G4brym/R2-Explorer/template" +``` + +This command with automatically create the project files locally and install all dependencies. + + +!!! note + + This uses the official create-cloudflare package, your wrangler informations are never shared with r2-explorer! + + +## 3rd Method (manual template) + +If you prefer to do the things yourself, there is a project template available on +[github here](https://github.com/G4brym/R2-Explorer/tree/main/template), that you can use. diff --git a/docs/pages/getting-started/deploying.md b/docs/pages/getting-started/deploying.md new file mode 100644 index 0000000..ef17f01 --- /dev/null +++ b/docs/pages/getting-started/deploying.md @@ -0,0 +1,17 @@ +To deploy your application is just need to be in its root folder, in the same level as the `wrangler.toml` file. + +To deploy, run the `wrangler deploy` command, wrangler will then start to build and deploy your application. + +If you are not logged in yet, it will prompt you to do so. +Otherwise, the deploy will go trough and print you the application url. + +```bash +$ wrangler deploy + ⛅️ wrangler 3.5.1 +------------------ +Total Upload: 2161.41 KiB / gzip: 662.18 KiB +Uploaded my-r2-explorer (4.09 sec) +Published my-r2-explorer (6.69 sec) + https://my-r2-explorer.g4brym.workers.dev +Current Deployment ID: efa04204-488e-4145-bb2d-7805c8e0c6b1 +``` diff --git a/docs/pages/getting-started/security.md b/docs/pages/getting-started/security.md new file mode 100644 index 0000000..eacadb6 --- /dev/null +++ b/docs/pages/getting-started/security.md @@ -0,0 +1,65 @@ +## Basic Auth + +Basic Auth was added in the `v1.0.2`, with support for multiple users. + +To enable this feature, update your `src/index.ts` file with the desired usernames and passwords. + +```ts title="src/index.ts" +import { R2Explorer } from 'r2-explorer'; + +export default R2Explorer({ readonly: false, basicAuth: [{ + username: 'teste', + password: 'abc' + },{ + username: 'anotherUser', + password: '123567' + }] +}); +``` + +After this, just deploy your application normally with: + +```bash +wrangler deploy +``` + +--- + +You can also define just a single user like this: + +```ts title="src/index.ts" +import { R2Explorer } from 'r2-explorer'; + +export default R2Explorer({ readonly: false, basicAuth: { + username: 'anotherUser', + password: '123567' + } +}); +``` + + +## Authenticating with Cloudflare Access + +In order to enable Cloudflare Access authentication, you only need to get your team name. + +You can find the team name, in the Zero trust dashboard -> Settings -> Custom Pages -> Team domain. + +In my account the team name is `r2explorer`. + + + +--- + +Now update your `src/index.ts` file with the team name, like this: + +```ts title="src/index.ts" +import { R2Explorer } from 'r2-explorer'; + +export default R2Explorer({ readonly: false, cfAccessTeamName: 'r2explorer' }); +``` + +After this, just deploy your application normally with: + +```bash +wrangler deploy +``` diff --git a/docs/pages/getting-started/updating-your-project.md b/docs/pages/getting-started/updating-your-project.md new file mode 100644 index 0000000..bc6eb8c --- /dev/null +++ b/docs/pages/getting-started/updating-your-project.md @@ -0,0 +1,34 @@ +R2 Explorer receives updates regularly, you will be prompted to update your application inside your +instance, in the bottom left connor, like this: + + + +## Manual update + +In order to update your application, just run: + +```bash +npm install r2-explorer@latest --save +``` + +Then proceed to deploy your application: +```bash +wrangler deploy +``` + +## Update using github actions + +You can check if your workers needs to update in fork github repository, by looking into the commits behind +section. + +To start the update, just click sync fork and then click update branch. + +This will update your fork and trigger an automatic deploy to update your Cloudflare worker. + +!!! warning + + Update using github actions, **requires** you to setup your instance following this [tutorial here](./creating-a-new-project.md). + + + + diff --git a/docs/pages/guides/continue-using-legacy-dashboard.md b/docs/pages/guides/continue-using-legacy-dashboard.md new file mode 100644 index 0000000..d265331 --- /dev/null +++ b/docs/pages/guides/continue-using-legacy-dashboard.md @@ -0,0 +1,18 @@ +The new dashboard v2 is now stable, and we are no longer providing update to the legacy (dashboard v1) version. + +But if you want, you can keep using the legacy version, by defining `dashboardUrl` in your `index.js` file, like this: + +```js title="src/index.js" +import { R2Explorer } from 'r2-explorer'; + +const explorer = R2Explorer({ + // ... other settings, you may have + dashboardUrl: "https://dashboard-v1.r2-explorer-dashboard.pages.dev/", +}) + +export default { + async fetch(request, env, context) { + return explorer(request, env, context) + } +}; +``` diff --git a/docs/pages/guides/migrating-to-1.0.md b/docs/pages/guides/migrating-to-1.0.md new file mode 100644 index 0000000..d05a4c1 --- /dev/null +++ b/docs/pages/guides/migrating-to-1.0.md @@ -0,0 +1,70 @@ +## What changed + +- The UI/Dashboard is no longer bundled with in the worker +- The way your personal worker exported the R2 Explorer instance is different + +## Updating your worker + +Why is the `export default` change required? + +This change is required to support more features in the near future, like the new [Email Explorer](setup-email-explorer.md). + + +Your `src/index.js` should look like this currently: +```js title="src/index.js" +import { R2Explorer } from 'r2-explorer'; + +const explorer = R2Explorer({ readonly: false, cors: true }) + +export default { + async fetch(request, env, context) { + return explorer(request, env, context) + } +}; +``` + +And you should update it to look like this: +```js title="src/index.js" +import { R2Explorer } from 'r2-explorer'; + +export default R2Explorer({ readonly: false, cors: true }); +``` + +!!! note + + Notice all the configs and everything else is exacly the same, you should only update the export default to be + the instance of the `R2Explorer()` function. + +## Installing the latest version + + +To finish the update you should install the latest version with: + +```bash +npm install r2-explorer@latest --save +``` + +Then proceed to deploy your application: +```bash +wrangler deploy +``` + +## Why is the Dashboard no longer bundled in the worker? + +In the 0.x versions of R2 Explorer the UI/Dashboard was compiled and bundled with the worker in your personal account, +but recently the dashboard has been getting bigger with each release. And max worker size is 1MB compressed +(read more [here](https://developers.cloudflare.com/workers/platform/limits/#worker-size)). + +So it was decided that moving forward the project is getting split into Dashboard hosted on Cloudflare Pages and the +API hosted in Cloudflare Workers. To keep the theme of the project as to be simple for everyone to deploy, +the worker is going to proxy dashboard requests to the Pages project, so the casual user is still just going to +just deploy the Worker and never think about the Pages project. + +Advantages of this approach, as the Pages project is automatically deployed with each release by the maintainers of +R2 Explorer, users with the default settings are going to get new updates without having to update their worker (as +long as the update didn't require an API change). + +For anyone wanting to deploy their own Pages project, all you need to do is to Fork the +[github repo](https://github.com/G4brym/R2-Explorer), and create a new Cloudflare Pages project connected to your own +Git repository and set the Root directory to `packages/dashboard`, then in your `R2Explorer()` configuration define the +`dashboardUrl` setting to the url of your new project (ex: `https://demo.r2explorer.dev`). diff --git a/docs/pages/guides/migrating-to-1.1.md b/docs/pages/guides/migrating-to-1.1.md new file mode 100644 index 0000000..85dc9dd --- /dev/null +++ b/docs/pages/guides/migrating-to-1.1.md @@ -0,0 +1,39 @@ +## What changed + +- Refactored worker to use [hono](https://github.com/honojs/hono) + [chanfana](https://github.com/cloudflare/chanfana) +- Dashboard is now served via [workers static assets](https://developers.cloudflare.com/workers/static-assets/) + +## Updating wrangler + +```bash +npm install --save wrangler@latest +``` + +## Updating wrangler.toml + +Add this line to the top of your `wrangler.toml` file: +```toml +assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application" } +``` + +It should look something like this: +```toml +name = "r2-explorer" +compatibility_date = "2024-11-06" +main = "src/index.ts" +assets = { directory = "node_modules/r2-explorer/dashboard", binding = "ASSETS", html_handling = "auto-trailing-slash", not_found_handling = "single-page-application" } + +# ... buckets bellow this line +``` + +## Installing the latest version + + +```bash +npm install r2-explorer@latest --save +``` + +Then proceed to deploy your application: +```bash +wrangler deploy +``` diff --git a/docs/pages/guides/setup-email-explorer.md b/docs/pages/guides/setup-email-explorer.md new file mode 100644 index 0000000..18d883d --- /dev/null +++ b/docs/pages/guides/setup-email-explorer.md @@ -0,0 +1,58 @@ +## What is Email Explorer? + +Email Explorer is a feature, that allows you and your team to see and open email received using +[Cloudflare Email routing](https://www.cloudflare.com/developer-platform/email-routing/). + + + +It works by catching the emails you configure to send to your R2 Explorer instance, saving theses +in a R2 bucket and then exposing a UI built around the R2 API. + + +## Are there new features coming to Email Explorer? + +Yes, the features planned for the near future are: + +- Custom email folders +- Configure rules to send emails to specific folders (like gmail filters) +- Delete emails +- Move emails between folders +- Email Search + + +## Setup Email Explorer + +After having your worker updated and deployed in your Cloudflare account, head over to the Cloudflare Dash and open +the domain you want to setup. + +!!! warning + + Email Explorer requires that you have at least R2 Explorer `v1.0.0`. + + Follow the [create a new project](../getting-started/creating-a-new-project.md) or + [migrate to 1.0](./migrating-to-1.0.md) guides! + +Open the Email -> Email Routing + + + +Then click Routes and in the bottom select Edit in the Catch-all address. + + + +!!! note + + You can also setup individual email routes, intead of using the catch-all. + + +Finally click Send to a Worker, pick your R2 Explorer instance and click save. + + + +Congratulations! you will now be able to see all the emails you receive inside your R2 Explorer instance. + +By default your emails will end up in the 1º bucket you have, but you can overwrite it, read more +[here](/getting-started/configuration/#configuring-email-explorer-target-bucket). + + + diff --git a/docs/pages/index.md b/docs/pages/index.md new file mode 100644 index 0000000..0d7d684 --- /dev/null +++ b/docs/pages/index.md @@ -0,0 +1,83 @@ +--- +hide: + - navigation +# - toc +--- + +
+
++ A Google Drive Interface for your Cloudflare R2 Buckets! +
+ + + +
+ 
+ 
+