Kobelly/README.md

Kobelly Web Solutions

A professional Flask-based website for promoting small business web development services. Features multilanguage support (English, Dutch, French, German) with a simple JSON-based translation system and is fully dockerized for easy deployment.

Features

• 🌐 Multilanguage Support: English (EN), Dutch (NL), French (FR), German (DE) with JSON-based translations
• 📱 Responsive Design: Modern, mobile-friendly interface
• 🎨 Professional UI: Clean, modern design with Bootstrap 5
• 🐳 Docker Support: Easy containerization and deployment
• ⚡ Fast Performance: Optimized for speed and performance with minified assets
• 🔧 No Database Required: Simple, lightweight setup
• 🚀 Asset Optimization: CSS/JS minification with cache busting
• 📧 Contact Form: Fully functional email contact form
• 🗺️ SEO Optimized: Sitemap generation and robots.txt

Pages

• Home: Hero section, features, and service overview
• Services: Detailed service offerings with pricing information
• About: Company story, team, and values
• Contact: Contact form and business information
• Portfolio: Showcase of completed projects

Quick Start

Local Development (Recommended)

1. Install Python dependencies:

   pip install -r requirements.txt
   

2. Build assets (optional, for production-like experience):

   make build
   

3. Run the application:

   python app.py
   

4. Access the website: Open your browser and go to http://localhost:5000

Using Make Commands

The project includes a Makefile for common tasks:

make help          # Show all available commands
make install       # Install dependencies
make build         # Build minified assets
make clean         # Clean old assets
make run           # Run development server
make run-prod      # Run production server
make deploy        # Clean and build assets
make dev-setup     # Setup development environment

# Docker commands
make docker-run    # Run production Docker container
make docker-run-dev # Run development Docker container
make docker-stop   # Stop production container
make docker-stop-dev # Stop development container
make docker-logs   # View production logs
make docker-logs-dev # View development logs

Docker Deployment

Production Mode (Default)

1. Build and run with Docker Compose:

   docker-compose up --build
   

2. Or build and run manually:

   docker build -t kobelly-website .
   docker run -p 5000:5000 kobelly-website
   

Development Mode

For local development with Docker (with live reload and debug mode):

1. Build and run development container:

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

2. Or use Make commands:

   make docker-run-dev    # Start development container
   make docker-logs-dev   # View development logs
   make docker-stop-dev   # Stop development container
   

Development vs Production:

• Development: Debug mode enabled, live code reloading, unminified assets
• Production: Debug disabled, minified assets, optimized performance

Project Structure

Kobelly/
├── app.py                 # Main Flask application
├── requirements.txt       # Python dependencies
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Docker Compose configuration
├── docker-compose.dev.yml # Development Docker Compose
├── Makefile              # Build and deployment commands
├── build_assets.py       # Asset minification script
├── translation_manager.py # JSON-based translation system
├── test_translations.py  # Translation testing script
├── robots.txt            # Search engine configuration
├── static/               # Static assets
│   ├── css/              # CSS files
│   │   ├── main.css      # Main stylesheet
│   │   └── main.min.css  # Minified CSS (generated)
│   ├── js/               # JavaScript files
│   │   ├── main.js       # Main script
│   │   └── main.min.js   # Minified JS (generated)
│   └── images/           # Images and icons
├── templates/            # HTML templates
│   ├── base.html         # Base template with navigation
│   ├── index.html        # Homepage
│   ├── services.html     # Services page
│   ├── about.html        # About page
│   ├── contact.html      # Contact page
│   ├── portfolio.html    # Portfolio page
│   └── components/       # Reusable template components
│       ├── hero_section.html
│       ├── cta_section.html
│       ├── stats_section.html
│       └── testimonials_section.html
└── translations/         # JSON translation files
    ├── en.json           # English translations
    ├── nl.json           # Dutch translations
    ├── fr.json           # French translations
    └── de.json           # German translations

Multilanguage Support

The website supports four languages using a simple JSON-based translation system:

• 🇺🇸 English (EN) - Default
• 🇳🇱 Dutch (NL)
• 🇫🇷 French (FR)
• 🇩🇪 German (DE)

Users can switch languages using the language selector in the navigation bar or URL parameters (?lang=de). The language preference is stored in the session.

Translation System

The project uses a custom JSON-based translation system that:

• No compilation needed - Just edit JSON files directly
• Real-time updates - Changes appear immediately after restart
• Simple maintenance - Clear JSON structure
• Independent languages - Edit English without breaking translations

Adding New Translations

1. Add the string to your template:

   <h2>{{ t('New Section Title') }}</h2>
   

2. Add it to the translation files:

   // translations/en.json
   {
     "New Section Title": "New Section Title"
   }
   
   // translations/de.json  
   {
     "New Section Title": "Neuer Abschnittstitel"
   }
   

3. Restart your Flask app - Changes appear immediately!

Customization

Content Updates

1. Text Content: Edit the HTML templates in the templates/ directory
2. Translations: Update the .json files in the translations/ directory
3. Styling: Modify the CSS in static/css/main.css

Adding New Pages

1. Add a new route in app.py
2. Create a new template file in templates/
3. Add navigation link in templates/base.html

Updating Translations

The JSON-based system makes translation updates simple:

1. Edit translation files directly:

   # Open and edit the JSON files
   nano translations/en.json
   nano translations/de.json
   # etc.
   

2. Restart the application:

   python app.py
   

3. Test translations:

   python test_translations.py
   

Asset Optimization

The project includes automatic CSS and JavaScript minification with cache busting for optimal performance.

Asset Building

Development Mode:

• Uses unminified assets for easier debugging
• Assets are served directly from source files

Production Mode:

• Automatically serves minified assets
• Cache busting prevents browser caching issues
• Assets are optimized for faster loading

Building Assets

# Build minified assets
make build

# Clean old cache-busted assets
make clean

# Full deployment (clean + build)
make deploy

Asset Files

• CSS: static/css/main.css → static/css/main.min.css
• JavaScript: static/js/main.js → static/js/main.min.js

The build process creates cache-busted versions with MD5 hashes in the filename to ensure browsers always load the latest version.

Contact Form Setup

The website includes a fully functional contact form that sends email notifications. To set up email functionality:

1. Email Configuration

The application uses environment variables for email configuration. You can set these in your environment or create a .env file:

# For Gmail (recommended)
MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=True
MAIL_USERNAME=contact@kobelly.be
MAIL_PASSWORD=your-app-password-here
MAIL_DEFAULT_SENDER=contact@kobelly.be

2. For Gmail users:

• Enable 2-factor authentication on your Google account
• Generate an "App Password" in Google Account settings
• Use the app password as MAIL_PASSWORD

3. Alternative Email Providers

For other SMTP providers, update the settings accordingly:

# Example for Outlook/Hotmail
MAIL_SERVER=smtp-mail.outlook.com
MAIL_PORT=587
MAIL_USE_TLS=True

# Example for custom SMTP server
MAIL_SERVER=your-smtp-server.com
MAIL_PORT=587
MAIL_USE_TLS=True

4. Testing the Contact Form

1. Start the application
2. Navigate to the Contact page
3. Fill out and submit the form
4. Check your email for the notification

The form includes:

• Form validation (required fields, email format, phone format)
• Loading states (button shows spinner during submission)
• Success/error notifications (toast notifications)
• Email notifications (HTML and plain text formats)

Configuration

Environment Variables

• SECRET_KEY: Secret key for Flask sessions (default: 'your-secret-key-change-in-production')
• FLASK_ENV: Flask environment (development/production)
• FLASK_DEBUG: Debug mode (0=disabled, 1=enabled, defaults to 1 in development)
• MAIL_SERVER: SMTP server for email (default: smtp.gmail.com)
• MAIL_PORT: SMTP port (default: 587)
• MAIL_USE_TLS: Use TLS encryption (default: True)
• MAIL_USERNAME: Email username
• MAIL_PASSWORD: Email password
• MAIL_DEFAULT_SENDER: Default sender email

Environment Modes:

Development (Local):

FLASK_ENV=development
FLASK_DEBUG=1

Production (Docker):

FLASK_ENV=production
FLASK_DEBUG=0

Production Deployment

For production deployment:

1. Set a strong SECRET_KEY
2. Disable debug mode
3. Use a production WSGI server (e.g., Gunicorn)
4. Set up proper SSL/TLS certificates
5. Configure a reverse proxy (e.g., Nginx)

Technologies Used

• Backend: Flask 2.3.3
• Frontend: Bootstrap 5, Font Awesome
• Translation: Custom JSON-based system
• Containerization: Docker, Docker Compose
• Styling: Custom CSS with CSS variables
• Asset Management: Custom build script with CSS/JS minification
• Email: Flask-Mail

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

License

This project is created for demonstration purposes. Feel free to use and modify for your own business needs.

Support

For questions or support, please contact:

• Email: contact@kobelly.be
• Phone: +32 486 21 07 07
• Address: Blijkheerstraat 92, 1755 Pajottegem, Belgium

---

Kobelly Web Solutions - Professional web development for small businesses and entrepreneurs.