Update README.md to enhance project documentation and clarify setup instructions

2025-12-18 14:07:01 +08:00
parent c950a72fc8
commit 0a235a0ed2
1 changed files with 162 additions and 14 deletions
--- a/readme.md
+++ b/readme.md
@@ -1,23 +1,171 @@
-## Laravel PHP Framework
+# MerchBay

-[![Build Status](https://travis-ci.org/laravel/framework.svg)](https://travis-ci.org/laravel/framework)
-[![Total Downloads](https://poser.pugx.org/laravel/framework/downloads.svg)](https://packagist.org/packages/laravel/framework)
-[![Latest Stable Version](https://poser.pugx.org/laravel/framework/v/stable.svg)](https://packagist.org/packages/laravel/framework)
-[![Latest Unstable Version](https://poser.pugx.org/laravel/framework/v/unstable.svg)](https://packagist.org/packages/laravel/framework)
-[![License](https://poser.pugx.org/laravel/framework/license.svg)](https://packagist.org/packages/laravel/framework)
+A custom merchandise and apparel design platform built with Laravel 5.0, enabling users to create, customize, and order personalized products.

-Laravel is a web application framework with expressive, elegant syntax. We believe development must be an enjoyable, creative experience to be truly fulfilling. Laravel attempts to take the pain out of development by easing common tasks used in the majority of web projects, such as authentication, routing, sessions, queueing, and caching.
+## 🚀 Tech Stack

-Laravel is accessible, yet powerful, providing powerful tools needed for large, robust applications. A superb inversion of control container, expressive migration system, and tightly integrated unit testing support give you the tools you need to build any application with which you are tasked.
+- **Framework:** Laravel 5.0
+- **PHP:** 7.0 with native mcrypt support
+- **Web Server:** Apache 2.4
+- **Database:** MySQL
+- **Container:** Docker with Apache
+- **Reverse Proxy:** Traefik (for SSL/TLS and routing)

-## Official Documentation
+## 📋 Prerequisites

-Documentation for the framework can be found on the [Laravel website](http://laravel.com/docs).
+- Docker and Docker Compose
+- Git
+- Access to deployment server (for production/dev deployments)

-## Contributing
+## 🛠️ Local Development

-Thank you for considering contributing to the Laravel framework! The contribution guide can be found in the [Laravel documentation](http://laravel.com/docs/contributions).
+### Building the Docker Image

-### License
+```bash
+docker build -t merchbay:dev .
+```

-The Laravel framework is open-sourced software licensed under the [MIT license](http://opensource.org/licenses/MIT)
+### Running Locally
+
+```bash
+# Create .env file from example
+cp .env.example .env
+
+# Update .env with your local configuration
+# Set database credentials, mail settings, etc.
+
+# Run with docker-compose (customize docker-compose.yml for local setup)
+docker-compose up -d
+```
+
+### Environment Variables
+
+The following environment variables are required:
+
+#### Database Configuration
+- `DB_HOST` - Database host
+- `DB_PORT` - Database port (default: 3306)
+- `DB_DATABASE` - Database name
+- `DB_USERNAME` - Database username
+- `DB_PASSWORD` - Database password
+
+#### Application URLs
+- `APP_URL` - Application base URL
+- `PROD_PRIVATE` - Production private server URL
+- `IMAGES_URL` - Images server URL
+- `UPLOAD_URL` - Upload directory URL
+
+#### Mail Configuration
+- `MAIL_DRIVER` - Mail driver (smtp)
+- `MAIL_HOST` - SMTP host
+- `MAIL_PORT` - SMTP port
+- `MAIL_USERNAME` - SMTP username
+- `MAIL_PASSWORD` - SMTP password
+- `MAIL_ENCRYPTION` - Encryption type (tls/ssl)
+
+#### Third-Party Services
+- `CAPTCHA_SITE_KEY` - reCAPTCHA site key
+- `CAPTCHA_SECRET_KEY` - reCAPTCHA secret key
+- `ANALYTICS_SITE_ID` - Google Analytics site ID
+- `ANALYTICS_CLIENT_ID` - Google Analytics client ID
+- `ANALYTICS_SERVICE_EMAIL` - Google Analytics service email
+
+## 🚢 Deployment
+
+### Automated CI/CD with Gitea Actions
+
+This project includes automated deployment workflows using Gitea Actions:
+
+#### Development Deployment
+Push to the `dev` branch to automatically deploy to dev environment:
+```bash
+git push origin dev
+```
+- Deploys to: `https://dev.merchbay.app`
+
+#### Production Deployment
+Push to the `main` or `master` branch to automatically deploy to production:
+```bash
+git push origin main
+```
+- Deploys to: `https://merchbay.app`
+
+#### Docker Registry
+Create version tags to build and push to Docker registry:
+```bash
+git tag -a v1.0.0 -m "Release v1.0.0"
+git push origin v1.0.0
+```
+
+### Workflow Files
+
+- `.gitea/workflows/deploy-dev.yml` - Development deployment
+- `.gitea/workflows/deploy.yml` - Production deployment
+- `.gitea/workflows/build-push.yml` - Docker image build and push
+
+## 📁 Project Structure
+
+```
+merchbay/
+├── app/                    # Application core
+│   ├── Http/              # Controllers, middleware, routes
+│   ├── Models/            # Database models
+│   └── Services/          # Business logic services
+├── config/                # Configuration files
+├── database/              # Migrations and seeds
+├── public/                # Public assets (images, CSS, JS)
+├── resources/             # Views and frontend assets
+├── storage/               # Application storage
+├── docker-compose.yml     # Docker compose configuration
+├── Dockerfile             # Docker image definition
+└── docker-entrypoint.sh   # Container startup script
+```
+
+## 🔧 Development Notes
+
+### Storage Permissions
+
+The Docker entrypoint automatically creates and sets proper permissions for:
+- `storage/framework/views`
+- `storage/framework/cache`
+- `storage/framework/sessions`
+- `storage/logs`
+- `bootstrap/cache`
+
+### PHP Extensions
+
+The following PHP extensions are installed:
+- pdo_mysql
+- mbstring
+- exif
+- pcntl
+- bcmath
+- mcrypt (native in PHP 7.0)
+- tokenizer
+- zip
+- gd (with freetype and jpeg support)
+
+## 🐛 Troubleshooting
+
+### 500 Internal Server Error
+
+1. Check container logs: `docker logs merchbay_app`
+2. Verify storage permissions are set correctly
+3. Ensure all environment variables are configured in `.env`
+4. Check database connectivity
+
+### Storage Permission Issues
+
+The entrypoint script automatically fixes permissions on container start. If issues persist:
+```bash
+docker exec merchbay_app chown -R www-data:www-data storage bootstrap/cache
+docker exec merchbay_app chmod -R 775 storage bootstrap/cache
+```
+
+## 📄 License
+
+Proprietary - All rights reserved
+
+## 🤝 Support
+
+For support and questions, contact the development team.