131 lines
4.5 KiB
Markdown
131 lines
4.5 KiB
Markdown
# Profile Linker Application
|
|
|
|
This project consists of a React frontend and a FastAPI backend for managing a list of people's profiles.
|
|
|
|
## Getting Started with a New Project
|
|
|
|
This repository serves as a template for creating new projects. To create a new project:
|
|
|
|
1. Clone this repository
|
|
2. Run the initialization script with your desired app name:
|
|
|
|
```bash
|
|
./new_project.sh YourAppName
|
|
```
|
|
|
|
The script will:
|
|
- Replace all references to "ResumeFormatter" with your app name
|
|
- Delete the Git history and initialize a new Git repository
|
|
- Create a .env file with your app name
|
|
- Rename the project folder to your app name (lowercase)
|
|
- Delete itself after completion
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
/
|
|
├── frontend/ # React frontend
|
|
│ ├── components/ # React components
|
|
│ ├── services/ # API services
|
|
│ └── ... # Other frontend files
|
|
├── backend/ # FastAPI backend
|
|
│ ├── app/ # FastAPI application
|
|
│ │ ├── api/ # API endpoints
|
|
│ │ ├── core/ # Core application components
|
|
│ │ ├── crud/ # CRUD operations
|
|
│ │ ├── db/ # Database components
|
|
│ │ ├── models/ # Database models
|
|
│ │ ├── schemas/ # Pydantic schemas
|
|
│ │ └── main.py # FastAPI application
|
|
│ ├── main.py # Entry point
|
|
│ └── requirements.txt # Python dependencies
|
|
├── .gitea/ # Gitea configuration
|
|
│ └── workflows/ # Gitea Actions workflows
|
|
├── docker-compose.yml # Docker Compose configuration
|
|
└── README.md # This file
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
The application uses environment variables for configuration. Create a `.env` file in the root directory with the following variables:
|
|
|
|
```
|
|
APP_NAME=ResumeFormatter
|
|
```
|
|
|
|
You can also use the provided `.env.example` file as a template.
|
|
|
|
## URL Structure
|
|
|
|
The application follows a specific URL structure based on the APP_NAME environment variable:
|
|
|
|
- Frontend: `http://localhost:8080/{APP_NAME}`
|
|
- API: `http://localhost:8080/{APP_NAME}/api`
|
|
- API Documentation: `http://localhost:8080/{APP_NAME}/api/docs`
|
|
- Static Assets: `http://localhost:8080/{APP_NAME}/assets`
|
|
|
|
This structure allows for multiple applications to be hosted under the same domain with different paths.
|
|
|
|
## Running the Application with Docker
|
|
|
|
1. Build and start the containers:
|
|
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
2. Access the application at http://localhost:8080/ResumeFormatter
|
|
3. Access the API at http://localhost:8080/ResumeFormatter/api
|
|
4. Access the API documentation at http://localhost:8080/ResumeFormatter/api/docs
|
|
|
|
## API Endpoints
|
|
|
|
The API provides the following endpoints:
|
|
|
|
- `GET /ResumeFormatter/api/people`: Get all people
|
|
- `POST /ResumeFormatter/api/people`: Create a new person
|
|
|
|
## Frontend Integration
|
|
|
|
The backend serves the frontend as static assets. The frontend is configured to use the APP_NAME as the base path for all assets and API calls. Key integration points:
|
|
|
|
1. **Vite Configuration**: The frontend uses Vite with a base path set to `/{APP_NAME}/` in `vite.config.ts`
|
|
2. **API Service**: The frontend API service uses `/{APP_NAME}/api` as the base URL for all API calls
|
|
3. **Static Assets**: All static assets are served under the `/{APP_NAME}/assets` path
|
|
|
|
## Database
|
|
|
|
The application uses SQLite for data storage. The database file is created at `./ResumeFormatter.db` in the root directory.
|
|
|
|
## Continuous Integration
|
|
|
|
This project includes a Gitea Actions workflow for building and pushing Docker images to Docker Hub. The workflow is triggered on pushes and pull requests to the `dev` branch.
|
|
|
|
### Gitea Actions Workflow
|
|
|
|
The workflow performs the following steps:
|
|
|
|
1. Installs required packages (Node.js, Git, Docker)
|
|
2. Checks out the code
|
|
3. Sets deployment variables based on branch name and .env file
|
|
4. Logs in to Docker Hub using the provided variables and secrets
|
|
5. Builds and pushes the Docker image with tags:
|
|
- `latest` (for main branch) or `dev` (for dev branch)
|
|
- The commit SHA
|
|
|
|
### Required Variables and Secrets
|
|
|
|
The following variables and secrets need to be set in the Gitea repository:
|
|
|
|
- `REGISTRY_USERNAME` (variable): Your Docker Hub username
|
|
- `REGISTRY_TOKEN` (secret): Your Docker Hub access token
|
|
|
|
### Image Naming
|
|
|
|
The Docker image will be named using the APP_NAME from the .env file:
|
|
|
|
```
|
|
{REGISTRY_USERNAME}/{APP_NAME}:latest
|
|
{REGISTRY_USERNAME}/{APP_NAME}:{commit-sha}
|
|
```
|