maria_prisma_finance

A new Flutter project.

Getting Started

This project is a starting point for a Flutter application.

A few resources to get you started if this is your first Flutter project:

• Lab: Write your first Flutter app
• Cookbook: Useful Flutter samples

For help getting started with Flutter development, view the online documentation, which offers tutorials, samples, guidance on mobile development, and a full API reference.

Deploying the Flutter Web app on a KingHost VPS

The project builds a static Flutter Web bundle that can be served from any web server. The instructions below outline how to deploy the site to your existing KingHost VPS, where Docker Compose and Traefik are already managing the backend stack.

1. Prerequisites

• Flutter SDK installed locally (stable channel recommended) and dependencies fetched with flutter pub get.
• Access to the KingHost VPS over SSH with permission to manage Docker and Docker Compose.
• An existing Traefik reverse-proxy container configured for HTTPS termination (as in your backend stack).
• Control over the domain in Route53 to create DNS records pointing to the VPS.

2. Build the Flutter Web bundle

1. On your development machine, update dependencies and produce the optimized build (injecting the backend URL via --dart-define):

   fvm flutter pub get
   fvm flutter build web \
     --dart-define=BASE_URL='https://api.maria.alemdatech.com/' \
     --dart-define=ENV='Production'  \
     --pwa-strategy=offline-first \
     --release

   The build artifacts will be generated under build/web/.

   Notes:

   • BASE_URL is read by AppConfig.baseUrl at compile time. Change the value per environment (dev/stage/prod).
   • You can pass multiple --dart-define flags for other variables if needed.
   • For mobile/desktop builds, use the same flag, e.g. flutter build apk --dart-define=BASE_URL=https://api.seudominio.com.

Then, copy the files:

cp -a ./build/web ../backend/web/

2. (Optional) Version the build output by copying build/web into a folder such as deploy/web-$(date +%Y%m%d) so you can roll back if needed.

3. Prepare a lightweight web server container

Flutter Web outputs static assets that can be served efficiently with Nginx. Create a folder alongside your backend Compose files (e.g., ~/apps/maria_prisma_web/) on the VPS and add the following files:

Dockerfile

FROM nginx:stable-alpine
COPY web /usr/share/nginx/html

.dockerignore

**
!web/**

Copy the content of build/web from your workstation to ~/apps/maria_prisma_web/web (using scp, rsync, or your preferred deploy tool). Each deployment replaces the contents of this web/ folder.

4. Integrate with Docker Compose and Traefik

Extend your existing docker-compose.yml (or create an override file) with a new service. The example below assumes your backend stack already defines a traefik service and a shared network named proxy:

services:
  maria_prisma_web:
    build: ./maria_prisma_web
    container_name: maria_prisma_web
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.maria_prisma_web.rule=Host(`app.seudominio.com`)"
      - "traefik.http.routers.maria_prisma_web.entrypoints=websecure"
      - "traefik.http.routers.maria_prisma_web.tls.certresolver=letsencrypt"
      - "traefik.http.services.maria_prisma_web.loadbalancer.server.port=80"
    networks:
      - proxy

networks:
  proxy:
    external: true

Adjust the host (app.seudominio.com) to match the subdomain you want to expose. If your Compose file already declares the proxy network, omit the networks block at the bottom to avoid redeclaration. Rebuild and start the stack:

docker compose build maria_prisma_web
docker compose up -d maria_prisma_web

Traefik will route HTTPS traffic for the configured host to the Nginx container, automatically generating TLS certificates if you have configured a cert resolver such as letsencrypt.

5. Configure DNS in Route53

• Create or update an A record in the hosted zone for the chosen subdomain (e.g., app.seudominio.com) pointing to the public IP address of the KingHost VPS. If you are using an existing wildcard certificate with Traefik, ensure the DNS record aligns with the wildcard.
• Allow DNS propagation (can take a few minutes). You can verify with dig app.seudominio.com or online DNS lookup tools.

6. Deploy updates

For subsequent releases:

1. Re-run the build command locally to refresh build/web.
2. Sync the new build to ~/apps/maria_prisma_web/web on the VPS.
3. Rebuild and restart the container:

   docker compose build maria_prisma_web
   docker compose up -d maria_prisma_web

   Docker will copy the updated assets into the image and Traefik will continue routing traffic without downtime.

7. Troubleshooting tips

• Use docker compose logs -f maria_prisma_web to inspect Nginx access logs.
• Ensure the Flutter app’s base href is set correctly (the default generated index.html already uses /). If serving from a sub-path, update <base href="/subcaminho/"> inside web/index.html before building.
• If assets are cached aggressively, instruct users to refresh with cache invalidation (Ctrl+F5) or bump the --base-href and --pwa-strategy settings to adjust service worker behavior.

Following these steps keeps the frontend deployment consistent with your existing Docker/Trafik infrastructure on KingHost, while letting Route53 continue to manage DNS for the domain.

Perguntas frequentes

Posso expor um segundo subdomínio na mesma VPS sem conflito de portas?

Sim. O Traefik fica escutando as portas 80/443 na VPS e faz o roteamento por host header. Basta adicionar uma nova regra Host(app.seudominio.com) (ou o subdomínio desejado) nas labels do serviço. Mesmo que os containers internos também usem a porta 80, o Traefik encaminha o tráfego para o container correto com base no domínio, evitando conflitos.

Por que o Dockerfile copia os arquivos para uma imagem Nginx?

O build do Flutter Web gera apenas arquivos estáticos (HTML, JS, CSS, assets). A imagem nginx:stable-alpine já traz um servidor HTTP otimizado para servir arquivos estáticos. Ao copiar a pasta web/ para /usr/share/nginx/html, o Nginx disponibiliza o conteúdo imediatamente sem precisar de código adicional.

Como Traefik e Nginx funcionam juntos?

O Traefik atua como proxy reverso na borda, terminando TLS e recebendo as conexões externas. Ele encaminha a requisição para o container maria_prisma_web usando a rede Docker interna. Dentro desse container, o Nginx atende a porta 80 e entrega os arquivos estáticos do Flutter. Dessa forma, Traefik cuida do roteamento e certificados, enquanto o Nginx foca em servir o frontend.