facebook_sharing_webtool/README.md

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.

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.

Requirements

• Node.js 22 or newer for local development
• Docker Engine with the Compose plugin for production deployment on Ubuntu

Local development

cp .env.example .env
npm install
npm run dev

The development server prints its local URL. Run all checks with:

npm run validate
npm run typecheck
npm test
npm run 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.

Ubuntu deployment

On the Ubuntu server, copy or clone this repository. Set the real public URL before building, then start the container:

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:

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:

https://crr.jcarreira.pt  ->  http://UBUNTU_SERVER_PRIVATE_IP:8080

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 src/content/events/. 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 src/content/events/festas-2026.md to a new kebab-case filename.
2. Update the title, slug, dates, poster path, Facebook post URL, and suggested text.
3. Add the poster to public/images/events/.
4. Set exactly one event to active: true; mark the previous event false.
5. Run npm run validate and rebuild the Docker image.

Historical event files stay published at /partilhar/<slug> after they stop being active. No Vue source changes are required for a normal new event.

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 template

---
title: "Nome do evento"
slug: "nome-do-evento-2027"
active: false
date:
  start: "2027-09-05"
  end: "2027-09-07"
location:
  name: "Centro Recreativo da Rebolaria"
  locality: "Rebolaria, Batalha"
poster: "/images/events/nome-do-evento-2027.jpg"
facebook:
  url: "https://www.facebook.com/..."
  embed: true
share:
  text: |
    Texto sugerido para quem vai partilhar.
---

## Sobre o evento

Descrição visível do evento.

## Programa

- 19h00 - Abertura

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.