message-board

Message Board

CI/CD
Package
Meta

---

A Message Board that will display submitted messages.

• Documentation
• Glossary
• Images
• References
• Telemetry

Executive Summary

IDE

We recommend the use of Cursor.io as the Integrated Development Environment (IDE) for this project.

Server

Getting your code up and running on your own system.

Note: Make sure you fulfill the requirements.

1. Installation process:

   $ cd server
   $ hatch --version # optional, will print the version of our package to the terminal without modifying the source directory (e.g. `0.0.1`).
   # Without hatch: $ python src/message_board/app.py
   $ hatch env create # optional, if the default env already exists you will be told
   $ hatch shell # spawn a shell within an environment
   (server) $ pip show message-board-server # optional, shows the project details, here 'message-board-server', from `pyproject.toml`
   # Name: message-board-server
   # Version: 0.1.0 # it takes this from src/message_board/__about__.py
   # ...
   (server) $ python -c "import sys;print(sys.executable)" # optional, see where your environment's python is located
   (server) $ pip install --upgrade pip # optional, the `run` command allows you to execute commands in an environment as if you had already entered it.
   (server) $ exit # optional, type `exit` to leave the environment

   NOTE: The modern way is to use pyproject.toml to install dependencies, not ```requirements.txt. Hence there should not be a requirements.txt file.

   === START: UPDATE THIS SECTION FOR message board ===

   Package your site with webpack: Once you have a website that is good enough for you to use, you have to package the application with webpack. This package folder is listed in .gitignore to avoid it to be committed to git.

   All of the setup should be ready by now so all you have to do:

   1. $ hatch shell
   2. (threagile-monitoring) $ cd src/threagile_monitoring
   3. (threagile-monitoring) $ npm install
   4. (threagile-monitoring) $ npm run build

   This will create the app.js file - which contains all components - in /src/threagile_monitoring/static/js/.

   Development with webpack: If you are still developing your website, in a separate terminal session, after having followed the above installation process, do this:

   1. $ hatch shell
   2. (threagile-monitoring) $ cd src/threagile_monitoring
   3. (threagile-monitoring) $ npm install
   4. (threagile-monitoring) $ npm run watch

   This will - in the separate terminal session (i.e. background) - constantly load the changes you make into the appropriate files, whilst you can can continue make those changes - in the initial terminal session (i.e. foreground). So you do not have to build your sources after each edit, it is taken care of automatically!

   To see the changes just save and reload your navigator (usually with F5).

   Make sure, to run your webpage when testing with backend functions, as follows:

   1. (threagile-monitoring) $ cd src/threagile_monitoring
   2. (threagile-monitoring) $ python app.py

   Test

   Test the application (frontend) this way:

   1. $ hatch shell
   2. (threagile-monitoring) $ cd src/threagile_monitoring
   3. (threagile-monitoring) $ npm install
   4. (threagile-monitoring) $ npm test
   5. (threagile-monitoring) $ npm test -- --coverage

   Run:

   If not developing, run the application (backend and frontend simultaneously) this way:

   $ hatch run python src/threagile_monitoring/app.py # starts the app 
   

2. Software dependencies

3. Latest releases

4. API references

5. Build and Test:

   To build your code, use:

   $ cd threagile-monitoring
   $ hatch build

   To use AI for pull request reviews, use:

   https://app.coderabbit.ai/dashboard (uses phpstan.neon)

   To run the application, use:

   Linux:

   $ export SECRET_KEY="secret"

   Windows:

   $ setx SECRET_KEY secret

   Then:

   $ cd threagile-monitoring
   # Without hatch: $ python src/threagile_monitoring/app.py
   $ hatch run python src/threagile_monitoring/app.py

   Then, navigate to http://127.0.0.1:5000/ in your web browser.

   To run tests, use:

   $ cd threagile-monitoring
   $ pip install pytest # optional
   $ pytest tests/

Docker

NOTE: For efficient use of resources, we use Podman instead of Docker!

Add these lines to your ~/.zshrc or ~/.bashrc:

alias docker=podman
alias docker-compose='podman compose'

Then reload your shell configuration:

$ source ~/.zshrc  # if using zsh
# or
$source ~/.bashrc # if using bash

Install podman-compose via pip:

$ pip install podman-compose

Verify the installation:

$ podman compose --version

Check if any Podman machines exist

$ podman machine list

If no machine exists, create one

$ podman machine init

Start the Podman machine

$ podman machine start

Set the socket path

$ export DOCKER_HOST=unix://$HOME/.local/share/containers/podman/machine/podman.sock

Verify Podman is working

$ podman ps

Start your Docker containers with:

$ cd containers/app

# For Linux
$ xhost +local:docker
$ docker compose --file docker-compose.dev.yml --project-name message-board-dev up --build -d

# For macOS with XQuartz
# On macOS we need to start XQuartz first. Here's the complete sequence:
# 1.Install XQuartz if you haven't already:
$ brew install --cask xquartz
# 2. Start XQuartz:
$ open -a XQuartz
# 3. You should see an "X" icon in your menu bar at the top of the screen. Click on it to open XQuartz preferences.
# 4. In XQuartz preferences, go to the "Security" tab and make sure "Allow connections from network clients" is checked.
# 5. Wait a few seconds for XQuartz to fully start up
# 6. Set display to local fisrt:
$ export DISPLAY=:0
# 7. Get your IP address
$ export IP=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
# 8. Allow X11 forwarding from your IP
$ xhost + $IP
# 9. Install podman and podman compose
$ pip install podman podman-compose
# 10. Initialize and start a new Podman machine with the correct mount (our cloned GitHub repository 'message-board' should reside in the '/usr/local/opt/code' directory)
$ podman machine init --now --volume /usr/local/opt/code:/home/user/code
$ podman machine set --rootful
$ podman machine start
$ podman volume create cloudbeaver-config
$ podman run --rm \
  -v cloudbeaver-config:/config \
  -v $(pwd)/initial-data.conf:/initial-data.conf:ro \
  alpine cp /initial-data.conf /config/
# 11. Then in your terminal:
# Remove the existing pod
$ podman pod rm -f pod_message-board-dev
# Remove any existing volumes
$ podman volume rm -f message-board-dev_dbvis-config
$ podman volume rm -f message-board-dev_message-board-data
# Verify everything is clean
$ podman pod ls
$ podman ps -a
$ podman volume ls
# Then start fresh
$ podman-compose --file docker-compose.dev.yml --project-name message-board-dev up -d --build
# or alternatively (since we have a mapping in ~/.zshrc file to map docker to podman):
$ docker compose --file docker-compose.dev.yml --project-name message-board-dev up -d --build
# The key is that XQuartz must be running before you execute the xhost command.

# For Windows with VcXsrv
$ set DISPLAY=host.docker.internal:0
$ docker compose --file docker-compose.dev.yml --project-name message-board-dev up --build -d

This will spin up three containers:

• message-board-server-dev (port 8080:5000)
• message-board-frontend-dev (port 80:3000)
• message-board-database-dev (port 5432:5432)
• message-board-db-gui-dev (port 5444:5444)

All four containers are running successfully. Let's verify each service:

1. Frontend (Vue.js):

• Visit http://localhost:80 in your browser

2. Backend (Flask):

• Visit http://localhost:8080/api/health in your browser
• Should return a health check response

3. Database (PostgreSQL):

• Already running and healthy (as shown in the status)
• Accessible on localhost:5432

4. CloudBeaver (DB GUI):

• Visit http://localhost:8978
• First-time setup:
• Create admin credentials when prompted
• Username: cbadmin
• Password: S3cr3tPwd
• Click "New Connection"
• Choose "PostgreSQL"
• Enter connection details:
• Host: database
• Port: 5432
• Database: message_board_db
• Username: db-user-dev
• Password: db-password-dev

DbVisualizer should connect to your PostgreSQL database using these credentials:

Server: database Port: 5432 Database: message_board_db Username: db-user-dev Password: db-password-dev

If DbVisualizer doesn't launch automatically, you can check the container logs:

$ docker logs message-board-db-gui-dev

API Documentation

Navigate to http://127.0.0.1:5000/docs in your web browser, or download the openapi.json from http://127.0.0.1:5000/openapi.json.

Metrics

Let a tool like Prometheus scrape http://127.0.0.1:9464/metrics.

___ NEW ___

Table of Contents

• Installation
• Version source
• Environments
• Build
• License

Installation

pip install threagile-monitoring

Version source

• The hatch-vcs version source plugin determines the project version using Git tags

Environments

• Defined neatly in a standalone hatch.toml
• The test matrix uses the hatch-containers plugin to run each environment inside Docker containers; usage can be seen in the test GitHub workflow

Build

• All build targets use the hatch-vcs build hook plugin to ship a _version.py file so the version can be used at runtime
• Wheels use the hatch-mypyc build hook plugin to first compile all code with Mypyc
• The build GitHub workflow shows how to:
  • use cibuildwheel to distribute binary wheels for every platform
  • use the app build target to build standalone distributions for every platform

License

threagile-monitoring is distributed under the terms of the MIT license.

=== END:  UPDATE THIS SECTION FOR message board ===

Frontend

1. Create the SvelteKit application:

$ cd containers/app
$ npx sv create frontend
Choose "SvelteKit demo"
Choose Yes, using Typescript syntax
Choose prettier, eslint, vitest, tailwindcss
Choose typography, forms, container-queries
Choose pnpm

Next steps:

│  1: cd frontend                                                          │
|  2: pnpm install @sveltejs/adapter-node --save-dev                       |
|  3: change in svelte.config.js:                                          |
|     FROM: import adapter from '@sveltejs/adapter-auto';                  |
|     TO:   import adapter from '@sveltejs/adapter-node';                  |
|     and:                                                                 |
|     FROM: adapter: adapter()                                             |
|     TO:   adapter: adapter({ out: 'build' })                             |
|  4: Add to package.json:                                                 |
|     "packageManager": "[email protected]",                                     |
│  5: git init && git add -A && git commit -m "Initial commit" (optional)  │
│  6: pnpm dev --open                                                      │
│                                                                          │
│  To close the dev server, hit Ctrl-C                                     │
│                                                                          │
│  Stuck? Visit us at https://svelte.dev/chat                              |
|                                                                          |
|  7: pnpm run build # creates a new build folder with production version  |
|  8: pnpm run preview # creates a preview of the production version       |

Memory Isues (On Mac):

Here are several steps you can take to address the memory issue:

1. Check Available Memory:

   • Open the Activity Monitor from the Apple menu.
   • Select the "Memory" tab.
   • Look at the "Usage" column to see how much memory is currently being used.

2. Close Unnecessary Applications:

   • Ensure that you are not running any unnecessary applications that may be consuming memory.

3. Clear Cache:

   • Sometimes, clearing the cache can help free up memory.

4. Restart Your Computer:

   • Sometimes, a simple restart can resolve memory issues.

5. Check for Updates:

   • Ensure that your operating system and applications are up to date.

6. Check for Memory Leaks:

   • Use tools like Valgrind or Instruments to check for memory leaks in your application.

7. Clear Docker resources:

   • Run the following command to remove all unused Docker resources:

   docker system prune -a
   

8. Docker Desktop Memory Limits You can limit Docker Desktop's resource usage: Open Docker Desktop Go to Settings/Preferences Select "Resources" Reduce memory limit (e.g., to 4-6GB depending on your system)

9. XQuartz Optimization Quit and restart XQuartz Consider using XQuartz only when needed rather than keeping it running

10. System-Level Solutions: Clear system cache:

    sudo purge
    

    Check swap usage:

    sysctl vm.swapusage
    

11. Long-term Solutions:

    • Upgrade your hardware:

    • Consider using a more powerful machine with more RAM.

    • Optimize your application:

    • Use memory profiling tools to identify and optimize memory-intensive operations.

    • Monitor and manage resources:

    • Use tools like htop or iostat to monitor system resources and manage them effectively.

    • Set up automatic cleanup scripts for Docker containers and images.

If the issue persists, you might want to: 1. Monitor which application is consuming the most memory 2. Consider alternatives to running all these applications simultaneously 3. Use lightweight alternatives where possible (e.g., Podman instead of Docker Desktop)

100 - Introduction

See README.md

200 - Requirements

See README.md

300 - Building Our Application

See README.md

400 - Conclusion

See README.md