jfmcarreira/facebook_sharing_webtool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: update README

Browse Source
This commit is contained in:
jfmcarreira
2026-09-01 10:17:42 +01:00
parent a043f647bd
commit d99ecc8144
2 changed files with 46 additions and 1546 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CRR_EVENT_SHARING_TOOL_PLAN.md
-1479
View File
File diff suppressed because it is too large Load Diff
README.md
+46 -67
View File
@@ -1,89 +1,69 @@
# CRR Event Sharing Tool
Static website for the Centro Recreativo da Rebolaria (CRR) that helps people promote an event on Facebook. The permanent public address is `/partilhar`; it displays the one event marked as active.
Static website for sharing events from the Centro Recreativo da Rebolaria.
The tool intentionally does not try to publish to Facebook or use `sharer.php`. Facebook does not reliably permit a shared post to contain another Facebook post automatically. Instead, visitors copy the suggested text, open the original CRR post, choose **Partilhar** then **Escrever publicação**, paste the text, and publish.
## Deploy
## Requirements
- Node.js 22 or newer for local development
- Docker Engine with the Compose plugin for production deployment on Ubuntu
## Local development
The server needs Docker with Docker Compose. From the project directory, run:
```bash
cp .env.example .env
npm install
npm run dev
docker compose up --build
```
The development server prints its local URL. Run all checks with:
The website is available on port `8200`.
After changing an event or updating the website, rebuild the container:
```bash
npm run validate
npm run typecheck
npm test
npm run build
docker compose up --build
```
`npm run build` validates Markdown and poster files, type-checks Vue/TypeScript, then generates static HTML. Event routes are pre-rendered in `dist/partilhar/<slug>/index.html`; this makes per-event social metadata available to Facebook, WhatsApp, Messenger, and other crawlers that do not execute JavaScript.
## Add an event
## Ubuntu deployment
On the Ubuntu server, copy or clone this repository. Set the real public URL before building, then start the container:
```bash
cp .env.example .env
docker compose up -d --build
```
The included Compose service listens on `8080` and restarts unless stopped. It is intentionally HTTP-only. Put an existing reverse proxy in front of it to terminate TLS and forward the public domain to `http://127.0.0.1:8080` (or to the server's Docker address as appropriate).
The build reads `VITE_SITE_URL` from `.env`; it defaults to `https://crr.jcarreira.pt`. Set it to the exact HTTPS public URL, without a trailing slash. It is used for canonical, Open Graph, and Twitter image URLs, so rebuild after changing it:
```bash
docker compose up -d --build
```
### Pointing `crr.jcarreira.pt` to your reverse proxy
Create a DNS `A` record for `crr.jcarreira.pt` that points to your existing reverse proxy's public IPv4 address. If you use IPv6, add an equivalent `AAAA` record.
In that reverse proxy, create a TLS-enabled host for `crr.jcarreira.pt` and forward it using HTTP to the Ubuntu machine running this project on port `8080`:
Events and their images are stored together in `content/events/`:
```text
https://crr.jcarreira.pt -> http://UBUNTU_SERVER_PRIVATE_IP:8080
content/events/
├── festas-2026.md
├── festas-2026.jpeg
├── novo-evento.md
└── novo-evento.jpg
```
Preserve the `Host` header and pass the usual `X-Forwarded-For` and `X-Forwarded-Proto` headers. TLS certificates, HTTP-to-HTTPS redirects, and public ports `80`/`443` remain entirely managed by your reverse proxy.
The Ubuntu firewall should permit `8080/tcp` only from the reverse proxy's IP address. Do not expose port `8080` publicly.
The final image contains nginx and static files only. Node.js is used only in the multi-stage build.
## Managing events
Each event is one Markdown file in `content/events/`, separate from the Vue application source. Its YAML frontmatter is the source of structured data and its Markdown body is the event information shown on the page.
To add an event:
1. Copy `content/events/festas-2026.md` to a new kebab-case filename.
2. Update the title, slug, dates, poster filename, Facebook post URL, and suggested text.
3. Add the poster image next to that event's Markdown file in `content/events/`.
4. Set exactly one event to `active: true`; mark the previous event `false`.
5. Run `npm run validate` and rebuild the Docker image.
1. Copy an existing Markdown file in `content/events/`.
2. Give it a unique filename and slug.
3. Add its poster image to the same directory.
4. Set `poster` to the image filename.
5. Set the new event to `active: true`.
6. Set every other event to `active: false`.
7. Rebuild the Docker container.
Historical event files stay published at `/partilhar/<slug>` after they stop being active. No Vue source changes are required for a normal new event.
Exactly one event can be active. Inactive events remain available at `/partilhar/<slug>`.
The `facebook.url` must be the original public CRR Facebook post URL. In Facebook, open the post and use its timestamp or menu option to copy the post link. The optional embed may be blocked by privacy controls or Facebook; the ordinary link and the rest of the page always remain usable.
## Event format
### Event template
Each event is a Markdown file containing:
- `title`: event name.
- `slug`: unique URL name using lowercase letters, numbers, and hyphens.
- `active`: whether the event appears at `/partilhar`.
- `date.start` and `date.end`: quoted dates in `YYYY-MM-DD` format.
- `location`: venue name and optional locality.
- `poster`: image filename located next to the Markdown file.
- `facebook.url`: direct URL of the original public Facebook post.
- `facebook.embed`: whether to display the Facebook post on the page.
- `share.text`: suggested text for visitors to copy.
- Markdown below the frontmatter: event description and programme.
Supported poster formats are PNG, JPG, JPEG, WebP, and AVIF.
```markdown
---
title: "Nome do evento"
slug: "nome-do-evento-2027"
active: false
active: true
date:
start: "2027-09-05"
end: "2027-09-07"
@@ -96,20 +76,19 @@ facebook:
embed: true
share:
text: |
Texto sugerido para quem vai partilhar.
Texto sugerido para partilhar o evento.
Pode ter vários parágrafos.
---
## Sobre o evento
Descrição visível do evento.
Descrição do evento.
## Programa
### Sábado, 5 de setembro
- 19h00 - Abertura
- 22h00 - Atuação musical
```
Dates must use quoted `YYYY-MM-DD` values. Validation rejects malformed content, duplicate slugs, more than one active event, invalid date ranges or Facebook URLs, and missing posters.
## Caching and previews
nginx caches Vite's hashed assets for one year and serves HTML without aggressive caching, so a rebuilt event page is immediately suitable for a reverse proxy to fetch. Social platforms may retain their own preview cache after deployment; use their respective sharing/debugging tools when a preview needs refreshing.