A comprehensive full-stack portfolio application built with Nuxt 4, featuring real-time communication, authentication, and multi-platform support. For more detailed information, refer to the Nuxt documentation.

• Prerequisites
• Getting Started
• Development
• Environment Configuration
• Docker Setup
• Building for Production
• Mobile Application
• Electron Application
• Production Deployment
• Mail Server
• Security
• Troubleshooting

Before starting with this project, ensure you have the following tools installed on your system:

• Docker and Docker Compose
• Bun JavaScript runtime
• Git version control system

Docker Installation:

# Download and run the official Docker installation script
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Add current user to docker group (Linux only)
sudo usermod -aG docker $USER

Bun Installation:

# Using the official Bun installer
curl -fsSL https://bun.sh/install | bash

# Or using npm
npm install -g bun

Git Installation:

# For Ubuntu/Debian
sudo apt install git
# For macOS
xcode-select --install
# For Windows, download from https://git-scm.com/

git clone https://github.com/Bader-Idris/nuxt4-fullstack-portfolio.git ./portfolio

# It's recommended to rename the project directory to 'portfolio' if you didn't use the previous command
sudo mv nuxt4-fullstack-portfolio portfolio
cd portfolio

bun install

Before running the application, ensure your database schema is up-to-date by running the Prisma migrations:

bunx prisma migrate deploy
bunx prisma generate

To start the development server, navigate to http://localhost:3000:

bun run dev

Create your environment configuration from the example file:

cp .env.example .env

The project includes environment configuration for different platforms:

• .env.example - Main application environment variables
• .env.electron.example - Electron application environment variables
• .env.capacitor.example - Mobile application environment variables

# to access the cli:
docker exec -it mongo mongosh "mongodb://<Mongo_user>:<Mongo_password>@localhost:27017/portfolio?authSource=admin"

show dbs
// your MONGO_DB_NAME
use MONGO_DB_NAME
show collections
// for instance users collection
db.getCollection("users").find()
// to find in collections:
db.users.find({ field: "value" }) // such as
db.users.find({ "email": "contact@baderidris.com" })

// to modify the role based on email do:
db.users.updateOne(
  { "email": "contact@baderidris.com" },
  { $set: { "role": "admin" } }
)
// to delete do:
db.users.deleteOne({ "email": "contact@baderidris.com" })

# after you've done the backup command with:
docker exec mongo sh -c 'mongodump --archive --gzip -u <Mongo_user> -p <Mongo_password> --authenticationDatabase admin' > /path/to/your/backup-4.4.gz
# some data will be lose, I've seen that the chats were lost! but not the admin messages!

# Then do this command to restore data: (the best approach is to do sequential versioning as 4 -> 5 -> 6 etc...)

docker exec -i mongo mongorestore \
  --archive --gzip \
  -u <Mongo_user> \
  -p <Mongo_password> \
  --authenticationDatabase admin \
  < /path/to/your/backup-4.4.gz

# and do this for compatibility
docker exec -it mongo mongosh -u <Mongo_user> -p <Mongo_password> --authenticationDatabase admin --eval '
  db.adminCommand({ setFeatureCompatibilityVersion: "8.2", confirm: true });
  db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 });
'

# 1. Create a backup of your data
docker exec psql pg_dump -U postgres articles > articles_backup.sql

# 2. Preserve old data (Optional but recommended)
docker volume create portfolio_psql-data-v16
docker run --rm -v portfolio_psql-data:/from -v portfolio_psql-data-v16:/to alpine ash -c "cd /from ; cp -av . /to"

# 3. Update your Docker Compose file
# Change image to postgres:18-alpine
# Change mount from /var/lib/postgresql/data to /var/lib/postgresql

# 4. Start the new container and restore data
cat articles_backup.sql | docker exec -i psql psql -U postgres -d articles

The project now includes a dedicated backup service using nfrastack/container-db-backup that automatically backs up both PostgreSQL and MongoDB every 24 hours.

• Rotation: Keeps 7 days of backups by default (configurable via DEFAULT_CLEANUP_TIME).
• Storage: Backups are stored in the backup-data volume.
• S3 Support: To enable remote backups, uncomment and fill the S3 environment variables in compose.prod.test.yaml or compose.ssl.yaml.

To view backup status:

docker logs db-backup

To list backups:

docker exec db-backup ls -lh /backup

The project uses Docker Compose for a complete development environment that includes all necessary backend services.

1. Configure Environment Variables

   cp .env.example .env
   # Edit .env with your configuration

2. Start Docker Services

   docker compose -f b.dev.yml up -d --build

3. Access the Application

   • Frontend: http://localhost:3000
   • Backend services will be automatically configured

To deploy in production with SSL certificates:

docker compose -f ./a.prod-certbot.yml up -d --build

To build the application for production:

# make it yours
cp ./compose.prod.test.yaml.example ./compose.prod.test.yaml
# then stop dev if running, and start building!
docker compose -f b.dev.yml down; docker compose -f compose.prod.test.yaml up -d redis postgres mongo ; docker compose -f compose.prod.test.yaml build --progress=plain app; docker compose -f compose.prod.test.yaml up -d

To locally preview the production build:

bun run preview

To add Android and iOS support:

bunx cap add android ios

Create the mobile environment file:

cp .env.capacitor.example .env.capacitor
# Configure the environment variables

To customize your app icons, modify the icons in the /assets folder as desired, then run:

bunx capacitor-assets generate --assetPath "./assets" --ios --android

You can review the configuration requirements in the assets/requirements.md file.

To run properly and prevent the mobile app from crashing, you must have the file android/app/google-services.json. Check the Capacitor documentation and Firebase documentation.

To build the Android app, ensure you have Android Studio installed and set these environment variables:

• ANDROID_HOME
• CAPACITOR_ANDROID_STUDIO_PATH

<item name="android:windowOptOutEdgeToEdgeEnforcement">true</item>

This ensures proper display behavior on Android 15+ devices when using Capacitor with overlay=true settings.

You can check out the issue here

• Electron Application
• Electrobun Application
• Production Deployment ...

To create a production build for Electron:

1. Create the Electron environment file:

   cp .env.electron.example .env.electron
   # Configure the environment variables

2. Use the following commands to build the Electron application:

   • bun run build:electron: Build for the current platform
   • bun run build:electron:all: Build for Windows, macOS, and Linux
   • bun run build:electron:win: Build for Windows only
   • bun run build:electron:mac: Build for macOS only
   • bun run build:electron:linux: Build for Linux only
   • bun run build:electron:dir: Build in an unpackaged directory for testing

For Linux distributions, the following formats are supported:

• DEB: Best for Ubuntu/Debian. Smooth installation via the GUI or terminal using sudo dpkg -i <file>.deb.
• AppImage: Portable and works on most distributions. Ensure it has execution permissions:

  chmod +x portfolio.AppImage
  ./portfolio.AppImage

• Snap: Strictly confined and secure. Since local builds are unsigned, you must install using the terminal:

  sudo snap install --dangerous nuxt4-fullstack-portfolio_3.4.0_linux_amd64.snap

A modern, lightweight alternative to Electron using Bun and system webviews.

1. Use the existing Electron environment file or create a specific one if needed.

2. Use the following commands to build or develop with Electrobun:

   • bun run dev:electrobun: Run development mode with HMR and native window.
   • bun run build:electrobun: Build for the current platform.
   • bun run build:electrobun:all: Build for Windows, macOS, and Linux sequentially.
   • bun run build:electrobun:win: Build for Windows only.
   • bun run build:electrobun:mac: Build for macOS only.
   • bun run build:electrobun:linux: Build for Linux only.

Releases will be organized and timestamped in ./release/electrobun/${version}_${timestamp}/.

Make sure to update the domain name baderidris.com in the b.dev.yml file and associated configuration files with your own domain name.

Before starting, copy the example env file and fill in your secrets:

cp .env.ssl.example .env.production
# then edit .env.production and set all required values

Then launch with:

docker compose -f compose.ssl.yaml --env-file .env.production up -d

To automate certificate renewals, create a cron job by modifying the paths in the /server/config/nginx/ssl_renew.sh file, then add this to your crontab:

# To edit your crontab, run:
crontab -e

# Add the following line to schedule the renewal script:
0 12 * * * /home/bader/portfolio/server/config/nginx/ssl_renew.sh >> /var/log/cron.log 2>&1

After the initial deployment, you will need to force Certbot to renew the certificates to remove the --staging flag. It is recommended to create a separate compose file for this purpose and for future renewals.

The project includes a fully functional mail server setup running at mail.baderidris.com. It is built using Docker Mailserver and supports DKIM, SPF, DMARC, and MTA-STS.

For detailed instructions on how to configure and manage the mail server, including DNS records and user management, please refer to the Mail Server Setup Script and the detailed documentation.

To enhance the security of your application and prevent common attacks such as DDoS, Fail2Ban has been implemented.

The following files are included in the security configuration:

ls server/config/fail2ban/
# Contains:
# - filter.d directory
# - my_custom_jail.local file

Custom jails and filters have been created to allow users to add their configurations after installing the tool. This flexibility helps you tailor the security settings to your specific needs.

• pnpm Stability: Refer to the pnpm Stability Guide for instructions on locking dependency versions and fixing Docker build failures.
• Weak Server Builds: Refer to weak_servers.md for guidance on optimizing builds for limited resources
• Docker Issues: Ensure Docker and Docker Compose are properly installed and running
• Environment Variables: Make sure all required environment variables are properly configured

Join our community discussions! Feel free to communicate with the maintainer and other community members on GitHub Discussions.

Thank you for using the Portfolio Full-Stack Application! If you have any questions or need further assistance, feel free to reach out.