N-FIN-45: add documentation on how to use the app (#63)

Resolves #45

.env.example

@@ -0,0 +1,8 @@
+
+#
+# This environment file sets variables for the development
+# Database specifics are set in the docker-compose file and the ORIGIN is not required for local development
+#
+
+# prisma database url
+DATABASE_URL="postgresql://prisma:prisma@localhost:5432/finances?schema=public"

README.md

@@ -1,3 +1,70 @@
 # Next-Finances
 
 This is my simple finances tracker that I use to keep track of my spending.
+
+## Using the app
+
+### Understanding the Basics
+
+- **Entities**: The core building blocks of your finances.
+  - Accounts: Where you hold money (e.g., bank accounts, PayPal account, cash)
+  - Entities: Where you spend money (e.g., Walmart, Spotify, Netflix)
+- **Payments**: Record money movement.
+  - Expenses: Money leaving an Account. (Account -> Entity)
+  - Income: Money entering an Account. (Entity -> Account)
+- **Categories** *(optional)*: Add labels to Payments for better tracking.
+
+### Your First Steps
+
+- Set up: Create Entities and Accounts that reflect your finances.
+- Record a Payment:
+  - Enter the amount and date.
+  - Select payor and payee
+  - *(optional)* Assign a category or enter a note.
+- Explore: View your payment history and view your statics at the dashboard
+
+### Tips
+
+- Install the website as a PWA for easy access.
+- Get in the habit of recording Payments as they happen for accurate tracking.
+- Use categories to understand your spending patterns.
+
+## Development
+
+Clone this repository and run the following commands:
+
+```bash
+
+## create .env file
+cp .env.example .env
+
+## start the database
+docker compose -f docker/finances-dev/docker-compose.yml up -d
+
+## generate prisma client
+npx prisma generate
+
+## apply database migrations
+npx prisma migrate deploy
+
+## start the development server
+npm run dev
+
+```
+
+Then open [http://localhost:3000](http://localhost:3000) with your browser and create an account.
+While in development mode, you can generate sample data from the [Account page](http://localhost:3000/account).
+
+## Deployment
+
+Copy the [docker-compose.yaml](./docker/finances-prod/docker-compose.yaml) file and
+the [.env.example](./docker/finances-prod/.env.example) from 'docker/finances-prod' to your server.
+
+Rename the `.env.example` file to `.env` and adjust the required environment variables.
+
+The docker setup expects you to run a Traefik reverse proxy. It will then register itself automatically.
+If your setup is different, you will need to adjust the `docker-compose.yaml` file accordingly.
+
+The finances containers will automatically register themselves to a running watchtower container if it is present.
+
+Finally run `docker-compose up -d` on your server to start the application.

docker/finances-prod/.env.example

@@ -0,0 +1,11 @@
+
+# database configuration
+DB_USER="db_user"
+DB_PASSWORD="db_password"
+
+# prisma database url
+DATABASE_URL="postgresql://$DB_USER:$DB_PASSWORD@postgres:5432/finances?schema=public"
+
+APPLICATION_DOMAIN="finances.thielker.xyz"
+COOKIE_DOMAIN="$APPLICATION_DOMAIN"
+ORIGIN="https://$APPLICATION_DOMAIN"

docker/finances-prod/docker-compose.yaml

@@ -25,7 +25,7 @@ services:
     restart: unless-stopped
     labels:
       - "traefik.enable=true"
-      - "traefik.http.routers.xyz-next-finances.rule=Host(`finances.thielker.xyz`)"
+      - "traefik.http.routers.xyz-next-finances.rule=Host(`${APPLICATION_DOMAIN}`)"
       - "traefik.http.routers.xyz-next-finances.entrypoints=web, websecure"
       - "traefik.http.routers.xyz-next-finances.tls=true"
       - "traefik.http.routers.xyz-next-finances.tls.certresolver=lets-encrypt"
@@ -46,7 +46,7 @@ services:
     restart: unless-stopped
     labels:
       - "traefik.enable=true"
-      - "traefik.http.routers.xyz-next-finances-studio.rule=Host(`studio.finances.thielker.xyz`)"
+      - "traefik.http.routers.xyz-next-finances-studio.rule=Host(`studio.${APPLICATION_DOMAIN}`)"
       - "traefik.http.routers.xyz-next-finances-studio.entrypoints=web, websecure"
       - "traefik.http.services.xyz-next-finances-studio.loadbalancer.server.port=5555"
       - "traefik.http.routers.xyz-next-finances-studio.tls=true"

docker/finances-prod/traefik.toml

@@ -0,0 +1,13 @@
+[entryPoints]
+[entryPoints.web]
+address = ":80"
+#        [entryPoints.web.http.redirections.entryPoint]
+#            to = "websecure"
+#            scheme = "https"
+
+[entryPoints.websecure]
+address = ":443"
+
+[providers.docker]
+watch = true
+network = "web"

docker/finances-prod/traefik_setup.sh

@@ -0,0 +1,13 @@
+
+#
+# run this container on your server to use traefik as a reverse proxy
+#
+docker run -d \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v $PWD/traefik.toml:/traefik.toml \
+  -p 80:80 \
+  -p 443:443 \
+  --restart unless-stopped \
+  --network web \
+  --name traefik \
+  traefik:v2.10

docker/finances-prod/watchtower_setup.sh

@@ -0,0 +1,13 @@
+
+#
+# run this container on your server to keep the labeled containers up to date
+#
+# run 'docker login' to authenticate with your docker hub account
+# label your containers with 'com.centurylinklabs.watchtower.enable=true' to enable watchtower
+#
+docker run -d \
+  --name watchtower \
+  --restart unless-stopped \
+  -v $HOME/.docker/config.json:/config.json \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  containrrr/watchtower -s "*/30 * * * * *" --label-enable