133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
# cmc-sales
|
|
|
|
CMC Sales is a business management system with two applications:
|
|
|
|
- **PHP Application**: CakePHP 1.2.5 (currently the primary application)
|
|
- **Go Application**: Go + HTMX (used for select features, growing)
|
|
|
|
**Future development should be done in the Go application wherever possible.**
|
|
|
|
## Architecture
|
|
|
|
Both applications:
|
|
- Share the same MariaDB database
|
|
- Run behind a shared Caddy reverse proxy with basic authentication
|
|
- Support staging and production environments on the same server
|
|
|
|
The PHP application currently handles most functionality, while the Go application is used for select screens and new features as they're developed.
|
|
|
|
## Development Setup
|
|
|
|
### Quick Start
|
|
|
|
``` shell
|
|
git clone git@code.springupsoftware.com:springup/cmc-sales.git
|
|
cd cmc-sales
|
|
|
|
# Easy way - use the setup script
|
|
./start-development.sh
|
|
|
|
# Manual way
|
|
rsync -avz --progress cmc@sales.cmctechnologies.com.au:~/backups .
|
|
docker compose up --build
|
|
gunzip < backups/backup_*.sql.gz | mariadb -h 127.0.0.1 -u cmc -p cmc
|
|
```
|
|
|
|
### Access Applications
|
|
|
|
**Add to /etc/hosts:**
|
|
```
|
|
127.0.0.1 cmclocal
|
|
```
|
|
|
|
**Application URLs:**
|
|
- **CakePHP (Legacy)**: http://cmclocal - Original CakePHP 1.2.5 application
|
|
- **Go (Modern)**: http://localhost:8080 - New Go application with HTMX frontend
|
|
- **Database**: localhost:3306 (user: `cmc`, password: see `app/config/database.php`)
|
|
|
|
### Architecture
|
|
|
|
- **cmc-php**: Legacy CakePHP application (nginx proxied)
|
|
- **cmc-go**: Modern Go application (direct access on port 8080)
|
|
- **db**: Shared MariaDB database
|
|
- **nginx**: Reverse proxy for CakePHP app
|
|
|
|
Both applications share the same database, allowing for gradual migration.
|
|
|
|
### Database Migrations
|
|
|
|
Database schema changes are managed using [Goose](https://github.com/pressly/goose) migrations in the `go/sql/migrations/` directory.
|
|
|
|
**Creating a new migration:**
|
|
```bash
|
|
cd go
|
|
make migrate-create name=add_new_column_to_table
|
|
```
|
|
|
|
**Running migrations:**
|
|
```bash
|
|
cd go
|
|
make migrate # Apply all pending migrations
|
|
make migrate-status # Check migration status
|
|
make migrate-down # Rollback last migration
|
|
```
|
|
|
|
**Migration files** use the Goose format with `-- +goose Up` and `-- +goose Down` sections. See `go/sql/migrations/` for examples.
|
|
|
|
**Configuration:** Database connection settings are in `go/goose.env` (create from `goose.env.example`).
|
|
|
|
### Requirements
|
|
|
|
- **Go Application**: Requires Go 1.23+ (for latest sqlc)
|
|
- Alternative: Use `Dockerfile.go.legacy` with Go 1.21 and sqlc v1.26.0
|
|
|
|
## Deployment
|
|
|
|
### Prerequisites
|
|
|
|
The deployment scripts use SSH to connect to the server. Configure your SSH config (`~/.ssh/config`) with a host entry named `cmc` pointing to the correct server:
|
|
|
|
```
|
|
Host cmc
|
|
HostName node0.prd.springupsoftware.com
|
|
User cmc
|
|
IdentityFile ~/.ssh/cmc
|
|
```
|
|
|
|
### Deployment Procedures
|
|
|
|
Deploy to staging or production using the scripts in the `deploy/` directory:
|
|
|
|
**Deploy to Staging:**
|
|
```bash
|
|
./scripts/deploy/deploy-stg.sh
|
|
```
|
|
|
|
**Deploy to Production:**
|
|
```bash
|
|
./deploy/deploy-prod.sh
|
|
```
|
|
|
|
**Rebuild without cache (useful after dependency changes):**
|
|
```bash
|
|
./scripts/deploy/deploy-prod.sh --no-cache
|
|
./scripts/deploy/deploy-stg.sh --no-cache
|
|
```
|
|
|
|
### How Deployment Works
|
|
|
|
1. The deploy script connects to the server via the `cmc` SSH host
|
|
2. Clones or updates the appropriate git branch (`stg` or `prod`)
|
|
3. Creates environment configuration for the Go application
|
|
4. Builds and starts Docker containers using the appropriate compose file
|
|
5. Applications are accessible through Caddy reverse proxy with basic auth
|
|
|
|
### Deployment Environments
|
|
|
|
- **Staging**: Branch `stg` → https://stg.cmctechnologies.com.au
|
|
- **Production**: Branch `prod` → https://sales.cmctechnologies.com.au or https://prod.cmctechnologies.com.au
|
|
|
|
Both environments run on the same server and share:
|
|
- A single Caddy reverse proxy (handles HTTPS and basic authentication for both environments)
|
|
- Separate Docker containers for each environment's PHP and Go applications
|
|
- Separate MariaDB database instances |