chore: update example

Author: sylv

README.md

@@ -6,9 +6,9 @@
 </p>
 
 <p align="center">
-  <img src="https://skillicons.dev/icons?i=next,tailwind,nest,typescript,docker,graphql" />
+  <img src="https://skillicons.dev/icons?i=vite,tailwind,nest,typescript,docker,graphql" />
   <br/>
-  <a href="https://discord.gg/VDMX6VQRZm"><kbd>🔵 discord</kbd></a> <a href="https://micro.sylo.digital"><kbd>🟢 hosted instance</kbd></a>
+  <a href="https://discord.gg/VDMX6VQRZm"><kbd>🔵 discord</kbd></a> <a href="https://micro.sylo.digital"><kbd>🟣 hosted instance</kbd></a>
 </p>
 
 # micro
@@ -19,8 +19,6 @@ A vanity file sharing service with support for ShareX. You can see a preview at
   - [features](#features)
   - [screenshots](#screenshots)
   - [installation](#installation)
-    - [configuration](#configuration)
-    - [updating](#updating)
   - [development](#development)
     - [`web` package notes](#web-package-notes)
   - [todo](#todo)
@@ -45,6 +43,7 @@ A vanity file sharing service with support for ShareX. You can see a preview at
 - [x] Conversions (GIF>WebM, WebP>PNG, etc.)
 - [x] Purging of old and/or large files (`config.purge`).
 - [x] 2FA support
+- [X] Decay files to S3 to save space 
 
 ## screenshots
 
@@ -67,37 +66,7 @@ A vanity file sharing service with support for ShareX. You can see a preview at
 
 ## installation
 
-> [!NOTE]
-> If you need help, join the [discord server](https://discord.gg/VDMX6VQRZm). This guide assumes you are on linux with a basic understanding of linux and docker.
-
-> [!TIP]
-> If you are already familiar with docker, you can look at the [compose file](./example/compose.yml) and [config file](./example/.microrc.yaml) to get setup quickly. The below is a more detailed guide for inexperienced users.
-
-1. Install `git` and `docker`
-2. Download the files in this repository, `git clone https://github.com/sylv/micro.git`
-3. Copy the example configs to the current directory, `cp ./micro/example/* ./`
-4. Fill out `.microrc.yaml`, `Caddyfile` and `docker compose.yml`. **It is extremely important you read through each of the 3 files and make sure you understand what they do.** Specifically, `.microrc.yaml` contains a secret that handles authentication, if it is not a secure random string everyone can sign in as anyone they want without a password.
-5. Run `docker compose up -d` to start the database and micro.
-6. Get the startup invite by doing `docker compose logs micro` and copying the invite URL that should be somewhere towards the end of the log. Go to that URL to create the first account.
-
-Setup is now complete and your instance should be working.
-To add another user, sign in then go to `/api/invite` and copy the URL it gives you. This will be improved in the future.
-
-### configuration
-
-micro uses [venera](https://github.com/sylv/venera) to load configuration files. Configuration files are validated on startup, and may log errors if invalid setups are detected. The venera page has more information, but tl;dr:
-
-- `.microrc.yaml` is the main configuration file.
-- You can override any config value with an environment variable. The key `hosts.0.url` would be set as `MICRO_HOSTS__0__URL`
-- You can use other file formats, like JSON or TOML.
-
-### updating
-
-You should take a full database backup before updating, but you won't, will you?
-The database will be automatically migrated on startup.
-
-1. `docker compose pull micro`
-2. `docker compose up -d micro`
+[See the `example` directory](./example) for how to setup micro.
 
 ## development
 

compose.yml

@@ -1,6 +1,6 @@
 # THIS FILE IS FOR DEVELOPMENT ONLY.
+# PERSISTENCE IS NOT ENABLED, `docker compose down` WILL DELETE ALL DATA.
 # If you want complete examples on how to host micro, see the /examples directory.
-# Persistence is not setup for this postgres instance.
 version: "3"
 services:
   postgres:

example/Caddyfile

@@ -0,0 +1,55 @@
+# example
+
+This directory contains an example deployment for micro.
+It uses [docker](https://docker.com) and [cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/) to deploy it anywhere.
+
+## usage
+
+> [!NOTE]
+> If you need help, join the [discord server](https://discord.gg/VDMX6VQRZm). This guide assumes you are on linux with a basic understanding of linux and docker.
+
+> [!IMPORTANT]
+> This guide assumes you have installed docker and cloudflare tunnel. It also assumes you have basic knowledge of them. 
+> If you are stuck or discover problems with this guide, ask in the [discord server](https://discord.gg/VDMX6VQRZm) or look at other guides for discord/cloudflare tunnel.
+
+1. Clone the example to a local directory
+2. Fill out `micro.yaml`, each option is documented in the file. Most importantly, make sure `secret` is changed.
+3. Replace the postgresql password in `compose.yaml` with a secure password.
+4. Setup the tunnel
+   1. `docker compose exec tunnel cloudflared tunnel login`
+   2. `docker compose exec tunnel cloudflared tunnel create micro`
+   3. You will get a tunnel ID that looks like `168b9890-caa1-44c1-822b-12cf1a5e361e`, copy it and replace `YOUR_TUNNEL_ID` in `tunnel.yaml` with it.
+   4. Replace the `example.net` domain with your own domain in `tunnel.yaml`. 
+5. Start micro with `docker compose up -d`
+6. Run `docker compose logs micro`, the initial startup will log an invite link. Go to it and setup the first account, which is given admin permissions automatically.
+
+> [!TIP]
+> Consider swapping cloudflare tunnel for something else. It's used in this example for convenience as it works behind NATs and firewalls and provides automatic SSL. You might prefer using Caddy, nginx, traefik, or something else in its place.
+
+### configuration
+
+All the configuration options are listed in [the example config](./micro.yaml) file. [venera](https://github.com/sylv/venera) is used to load configs, which are validated at startup and may log errors if an invalid configuration is detected. The venera page has detailed information, but tl;dr:
+
+- `.microrc.yaml` is the main configuration file.
+- You can override any config value with an environment variable. The key `hosts.0.url` would be set as `MICRO_HOSTS__0__URL`
+- You can use other file formats, like JSON or TOML.
+
+### updating micro
+
+You should take a full database backup before updating, but you won't, will you?
+The database will be automatically migrated on startup, all you have to do is run a newer version of micro.
+
+1. `docker compose pull micro`
+2. `docker compose up -d micro`
+
+### updating postgresql
+
+Updating postgres is an involved process. Google will have better information. In general, you will want to do something like this:
+
+- Export your database to a `.sql` file, using something like `docker compose exec postgres pg_dump -U postgres -d micro > backup.sql`
+- Stop your database
+- Rename the database directory to something else, like `mv ./data ./data-old`
+- Update `compose.yaml` to point to the new postgres version, for example `postgres:16-alpine` is for v16 of postgres.
+- Start the database `docker compose up -d postgres`
+- Restore the database using the `.sql` file
+- Once it all checks out, you can delete the old database directory if you are confident you won't need it.

example/README.md

@@ -1,33 +1,26 @@
-version: '3'
 services:
   micro:
     image: sylver/micro:main
     restart: unless-stopped
     volumes:
-      - $PWD/.microrc.yaml:/usr/src/micro/.microrc.yaml
-      - $PWD/data:/data
-    # uncomment this if you dont care about https, then comment out the proxy service
-    # ports:
-    #   - 80:3000
+      - ./micro.yaml:/usr/src/micro/micro.yaml
+      - ./data:/data
+
   postgres:
-    image: postgres:12-alpine
+    image: postgres:16-alpine
     restart: unless-stopped
     environment:
-      # leaving this as default should be fine as postgres will only ever be exposed to services
-      # in this compose file, but you might still want to consider changing it to something more secure.
-      - POSTGRES_PASSWORD=youshallnotpass
+      - POSTGRES_PASSWORD=youshallnotpass # change this!
       - POSTGRES_USER=micro
       - POSTGRES_DB=micro
     volumes:
-      - $PWD/.pg-data:/var/lib/postgresql/data
-  # comment this out if you dont care about https, then uncomment the above ports
-  proxy:
-    image: caddy:2-alpine
+      - ./.pg-data:/var/lib/postgresql/data
+      
+  tunnel:
+    container_name: tunnel
+    image: cloudflare/cloudflared:latest
     restart: unless-stopped
-    ports:
-      - 80:80
-      - 443:443
+    command: tunnel run micro
     volumes:
-      - $PWD/.caddy-data:/data
-      - $PWD/.caddy-config:/config
-      - $PWD/Caddyfile:/etc/caddy/Caddyfile
+      - ./.cloudflared:/etc/cloudflared
+      - ./tunnel.yaml:/etc/cloudflared/config.yml

example/compose.yml

@@ -1,5 +1,5 @@
 # you can pass in most config options through environment variables, 
-# for example `DATABASE_URL` will override the databaseUrl in this config file.
+# for example `MICRO_DATABASE_URL` will override the databaseUrl in this config file.
 # remove the .yaml extension or change it to .json to use JSON-with-comments
 # ref: https://github.com/sylv/venera#sources
 

example/.microrc.yaml renamed to example/micro.yaml

@@ -0,0 +1,9 @@
+tunnel: YOUR_TUNNEL_ID
+
+ingress:
+  - hostname: "*.example.net"
+    service: http://micro:3000
+  - hostname: "example.net"
+    service: http://micro:3000
+
+  - service: http_status:404

example/tunnel.yaml

@@ -68,7 +68,7 @@ const schema = strictObject({
   ),
 });
 
-const data = loadConfig("micro");
+const data = loadConfig("micro", { pathHints: ["micro.yaml"] });
 const result = schema.safeParse(data);
 if (!result.success) {
   console.dir({ data, error: result.error }, { depth: null });