Skip to content

Commit 0eefd18

Browse files
soudissoudis
committed
chore: update docs for dev environment setup
1 parent 358070a commit 0eefd18

File tree

3 files changed

+243
-22
lines changed

3 files changed

+243
-22
lines changed

‎.env.example‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Environment variables declared in this file are automatically made available to Prisma.
2+
# See the documentation for more detail: https://pris.ly/d/prisma-schema#accessing-environment-variables-from-the-schema
3+
4+
# Prisma supports the native connection string format for PostgreSQL, MySQL, SQLite, SQL Server, MongoDB and CockroachDB.
5+
# See the documentation for all the connection string options: https://pris.ly/d/connection-strings
6+
7+
COMPOSE_PROJECT_NAME=soliloan
8+
DOCKER_IMAGE_TAG=dev
9+
ENVIRONMENT=dev
10+
11+
# Postgres
12+
# https://hub.docker.com/_/postgres/
13+
POSTGRES_DB=soliloan
14+
POSTGRES_PASSWORD=your_secure_postgres_password
15+
POSTGRES_USER=postgres
16+
17+
# Prisma
18+
# https://www.prisma.io/docs/reference/database-reference/connection-urls#env
19+
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"
20+
NEXTAUTH_SECRET="your_nextauth_secret_key_here"
21+
NEXTAUTH_URL="https://soliloan.localhost"
22+
NEXTAUTH_URL_INTERNAL="http://soliloan:3000"
23+
24+
SOLILOAN_DOMAIN="your-domain.com"
25+
SOLILOAN_PROJECT_NAME="Your Project Name"
26+
SOLILOAN_URL="https://soliloan.localhost"
27+
SOLILOAN_ADMIN_EMAIL="admin@your-domain.com"
28+
SOLILOAN_ADMIN_PASSWORD="your_admin_password"
29+
SOLILOAN_DEFAULT_LANGUAGE="de"
30+
31+
# SMTP Configuration
32+
SMTP_HOST="smtp.your-provider.com"
33+
SMTP_PORT="587"
34+
SMTP_USER="your-email@your-domain.com"
35+
SMTP_PASSWORD="your_smtp_app_password"
36+
SMTP_FROM="your-email@your-domain.com"

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ yarn-error.log*
3131
.pnpm-debug.log*
3232

3333
# env files (can opt-in for committing if needed)
34-
.env*
34+
.env
3535

3636
# vercel
3737
.vercel

‎README.md‎

Lines changed: 206 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,221 @@
1-
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
1+
# SoliLoan - Direct Credit Management Platform
22

3-
## Getting Started
3+
A modern Next.js application for managing direct credit (Direktkredit) operations, built with TypeScript, Prisma, and Docker.
44

5-
First, run the development server:
5+
## 🚀 Quick Start - Development Setup
66

7+
### Prerequisites
8+
9+
Before you begin, ensure you have the following installed on your system:
10+
11+
- **Docker** (version 20.10 or higher)
12+
- **Docker Compose** (version 2.0 or higher)
13+
- **pnpm** (version 8.0 or higher) - [Installation Guide](https://pnpm.io/installation)
14+
- **Node.js** (version 20 or higher) - Required for local development tools
15+
16+
### Step-by-Step Setup
17+
18+
#### 1. Clone the Repository
19+
20+
```bash
21+
git clone <repository-url>
22+
cd soliloan
23+
```
24+
25+
#### 2. Environment Configuration
26+
27+
Create your environment file from the example:
28+
29+
```bash
30+
cp .env.example .env
31+
```
32+
33+
#### 3. Configure Environment Variables
34+
35+
Edit the `.env` file and update the following variables with your actual values:
36+
37+
**Required Configuration:**
38+
- `POSTGRES_PASSWORD`: Set a secure password for your PostgreSQL database
39+
- `NEXTAUTH_SECRET`: Generate a secure secret key (you can use `openssl rand -base64 32`)
40+
- `SOLILOAN_DOMAIN`: Your domain name
41+
- `SOLILOAN_PROJECT_NAME`: Your project name
42+
- `SOLILOAN_ADMIN_EMAIL`: Admin user email
43+
- `SOLILOAN_ADMIN_PASSWORD`: Admin user password
44+
45+
**SMTP Configuration (for email functionality):**
46+
- `SMTP_HOST`: Your SMTP server host
47+
- `SMTP_PORT`: SMTP port (usually 587 for TLS)
48+
- `SMTP_USER`: Your email username
49+
- `SMTP_PASSWORD`: Your email password or app-specific password
50+
- `SMTP_FROM`: Sender email address
51+
52+
#### 4. Start the Development Environment
53+
54+
Use the provided Docker Compose command to start all services:
55+
56+
```bash
57+
pnpm docker:dev up
58+
```
59+
60+
This command will:
61+
- Build the Next.js application
62+
- Start PostgreSQL database
63+
- Start Traefik reverse proxy
64+
- Run database migrations
65+
- Seed the database with initial data
66+
- Start the development server
67+
68+
#### 5. Access the Application
69+
70+
Once all services are running, you can access:
71+
72+
- **Application**: https://soliloan.localhost
73+
- **Traefik Dashboard**: http://localhost:8080 (for debugging routing)
74+
75+
> **Note**: Make sure to add `soliloan.localhost` to your `/etc/hosts` file:
76+
> ```
77+
> 127.0.0.1 soliloan.localhost
78+
> ```
79+
80+
### Development Workflow
81+
82+
#### Available Commands
83+
84+
```bash
85+
# Start development environment
86+
pnpm docker:dev up
87+
88+
# Start in background (detached mode)
89+
pnpm docker:dev up -d
90+
91+
# View logs
92+
pnpm docker:dev logs -f
93+
94+
# Stop all services
95+
pnpm docker:dev down
96+
97+
# Rebuild and start (useful after dependency changes)
98+
pnpm docker:dev up --build
99+
100+
# Access application container shell
101+
pnpm docker:dev exec app sh
102+
```
103+
104+
#### Database Operations
105+
106+
The development setup automatically handles:
107+
- Database schema migrations via Prisma
108+
- Database seeding with initial data
109+
- Hot reloading of database changes
110+
111+
For manual database operations:
112+
113+
```bash
114+
# Access database directly
115+
pnpm docker:dev exec postgres psql -U postgres -d soliloan
116+
117+
# Run Prisma commands inside container
118+
pnpm docker:dev exec app pnpm prisma studio
119+
pnpm docker:dev exec app pnpm prisma db push
120+
pnpm docker:dev exec app pnpm prisma db seed
121+
```
122+
123+
### Architecture Overview
124+
125+
The development environment consists of three main services:
126+
127+
#### 1. Application Service (`app`)
128+
- **Base Image**: Node.js 20 with pnpm
129+
- **Port**: 3000 (internal)
130+
- **Features**:
131+
- Hot reloading with Turbopack
132+
- Volume mounting for live code changes
133+
- Automatic dependency installation
134+
- Database migration and seeding
135+
136+
#### 2. PostgreSQL Database (`postgres`)
137+
- **Image**: Official PostgreSQL
138+
- **Port**: 5432 (exposed for direct access)
139+
- **Features**:
140+
- Persistent data storage
141+
- Development-optimized configuration
142+
143+
#### 3. Traefik Reverse Proxy (`traefik`)
144+
- **Image**: Traefik v2.11.2
145+
- **Ports**: 80, 443, 8080
146+
- **Features**:
147+
- Automatic HTTPS with self-signed certificates
148+
- Load balancing
149+
- Development dashboard
150+
151+
### Troubleshooting
152+
153+
#### Common Issues
154+
155+
**1. Port Conflicts**
156+
If you encounter port conflicts, check what's running on ports 80, 443, 5432, or 8080:
157+
```bash
158+
sudo lsof -i :80
159+
sudo lsof -i :5432
160+
```
161+
162+
**2. Database Connection Issues**
163+
Ensure PostgreSQL is fully started before the application:
164+
```bash
165+
pnpm docker:dev logs postgres
166+
```
167+
168+
**3. Permission Issues**
169+
If you encounter permission issues with Docker volumes:
7170
```bash
8-
npm run dev
9-
# or
10-
yarn dev
11-
# or
12-
pnpm dev
13-
# or
14-
bun dev
171+
sudo chown -R $USER:$USER .
15172
```
16173

17-
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
174+
**4. SSL Certificate Issues**
175+
For local development, the application uses self-signed certificates. You may need to:
176+
- Accept the certificate in your browser
177+
- Add `soliloan.localhost` to your hosts file
178+
179+
#### Reset Development Environment
180+
181+
To completely reset your development environment:
182+
183+
```bash
184+
# Stop and remove all containers, networks, and volumes
185+
pnpm docker:dev down -v
186+
187+
# Remove any local changes to node_modules
188+
rm -rf node_modules
189+
190+
# Restart fresh
191+
pnpm docker:dev up --build
192+
```
18193

19-
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
194+
### Production Deployment
20195

21-
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
196+
This setup is optimized for development. For production deployment, refer to the staging configuration in `docker/compose.staging.yml` and ensure:
22197

23-
## Learn More
198+
- Use production-grade secrets
199+
- Configure proper SSL certificates
200+
- Set up monitoring and logging
201+
- Use external database services
202+
- Configure proper backup strategies
24203

25-
To learn more about Next.js, take a look at the following resources:
204+
### Contributing
26205

27-
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
28-
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
206+
1. Fork the repository
207+
2. Create a feature branch
208+
3. Make your changes
209+
4. Test thoroughly with the development environment
210+
5. Submit a pull request
29211

30-
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
212+
### Support
31213

32-
## Deploy on Vercel
214+
For issues and questions:
215+
- Check the troubleshooting section above
216+
- Review Docker and application logs
217+
- Create an issue in the repository
33218

34-
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
219+
---
35220

36-
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
221+
**Happy coding! 🎉**

0 commit comments

Comments
 (0)