feat: migrate Flask API to Go with JWT auth
This commit is contained in:
Cipher Vance
325
README.md
325
README.md
@@ -1,91 +1,336 @@
|
||||
Here's a rewritten README for your Go version:
|
||||
|
||||
```markdown
|
||||
# RideAware API
|
||||
|
||||
<i>Train with Focus. Ride with Awareness</i>
|
||||
|
||||
RideAware API is the backend service for the RideAware platform, providing endpoints for user authentication and structured workout management.
|
||||
RideAware API is the backend service for the RideAware platform, built with Go and PostgreSQL. It provides comprehensive endpoints for user authentication, profile management, and cycling performance tracking.
|
||||
|
||||
RideAware is a **comprehensive cycling training platform** designed to help riders stay aware of their performance, progress, and goals.
|
||||
RideAware is a **comprehensive cycling training platform** designed to help riders stay aware of their performance, progress, and goals.
|
||||
|
||||
Whether you're building a structured training plan, analyzing ride data, or completing workouts indoors, RideAware keeps you connected to every detail of your ride.
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Language**: Go 1.21+
|
||||
- **Database**: PostgreSQL
|
||||
- **ORM**: GORM
|
||||
- **Router**: Chi v5
|
||||
- **Auth**: JWT (Access + Refresh tokens)
|
||||
- **Email**: Resend
|
||||
- **Containerization**: Podman/Docker
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
Ensure you have the following installed on your system:
|
||||
|
||||
- Docker
|
||||
- Python 3.10 or later
|
||||
- pip
|
||||
- Go 1.21 or later
|
||||
- PostgreSQL 12 or later
|
||||
- Podman or Docker
|
||||
- Git
|
||||
|
||||
### Setting Up the Project
|
||||
|
||||
1. **Clone the Repository**
|
||||
1. **Clone the Repository**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/VeloInnovate/rideaware-api.git
|
||||
cd rideaware-api
|
||||
```
|
||||
|
||||
2. **Create a Virtual Environment**
|
||||
It is recommended to use a Python virtual environment to isolate dependencies.
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
```
|
||||
2. **Install Dependencies**
|
||||
|
||||
3. **Activate the Virtual Environment**
|
||||
- On Linux/Mac:
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
```
|
||||
- On Windows:
|
||||
```cmd
|
||||
.venv\Scripts\activate
|
||||
```
|
||||
|
||||
4. **Install Requirements**
|
||||
Install the required Python packages using pip:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
go mod download
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
### Configuration
|
||||
3. **Configure Environment Variables**
|
||||
|
||||
The application uses environment variables for configuration. Create a `.env` file in the root directory and define the following variables:
|
||||
Create a `.env` file in the root directory:
|
||||
|
||||
```
|
||||
DATABASE=<your_database_connection_string>
|
||||
```
|
||||
- Replace `<your_database_connection_string>` with the URI of your database (e.g., SQLite, PostgreSQL).
|
||||
```env
|
||||
# Database
|
||||
PG_USER=postgres
|
||||
PG_PASSWORD=your_password
|
||||
PG_HOST=localhost
|
||||
PG_PORT=5432
|
||||
PG_DATABASE=rideaware
|
||||
|
||||
### Running with Docker
|
||||
# Server
|
||||
PORT=5000
|
||||
|
||||
To run the application in a containerized environment, you can use the provided Dockerfile.
|
||||
# Security
|
||||
JWT_SECRET_KEY=your-super-secret-key-change-in-production
|
||||
|
||||
1. **Build the Docker Image**:
|
||||
# Email Service
|
||||
RESEND_API_KEY=re_your_resend_api_key
|
||||
SENDER_EMAIL=noreply@rideaware.app
|
||||
```
|
||||
|
||||
4. **Set Up the Database**
|
||||
|
||||
Ensure PostgreSQL is running and create the database:
|
||||
|
||||
```bash
|
||||
createdb rideaware
|
||||
```
|
||||
|
||||
GORM will automatically run migrations on startup.
|
||||
|
||||
### Running Locally
|
||||
|
||||
**Option 1: Direct Execution**
|
||||
|
||||
```bash
|
||||
docker build -t rideaware-api .
|
||||
go run main.go
|
||||
```
|
||||
|
||||
The API will be available at `http://localhost:5000`
|
||||
|
||||
**Option 2: Build and Run Binary**
|
||||
|
||||
```bash
|
||||
go build -o server .
|
||||
./server
|
||||
```
|
||||
|
||||
### Running with Podman/Docker
|
||||
|
||||
#### Quick Start (with build script)
|
||||
|
||||
```bash
|
||||
chmod +x build.sh
|
||||
./build.sh --run
|
||||
```
|
||||
|
||||
This will build the image and start a container.
|
||||
|
||||
#### Manual Build
|
||||
|
||||
1. **Build the Image**
|
||||
|
||||
```bash
|
||||
podman build -t rideaware:latest .
|
||||
```
|
||||
|
||||
2. **Run the Container**
|
||||
|
||||
```bash
|
||||
podman run -d \
|
||||
--name rideaware-api \
|
||||
-p 5000:5000 \
|
||||
--env-file .env \
|
||||
rideaware:latest
|
||||
```
|
||||
|
||||
3. **View Logs**
|
||||
|
||||
```bash
|
||||
podman logs -f rideaware-api
|
||||
```
|
||||
|
||||
The API will be available at `http://localhost:5000`
|
||||
|
||||
## API Documentation
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
docker run -d -p 5000:5000 --env-file .env rideaware-api
|
||||
GET /health
|
||||
```
|
||||
|
||||
The application will be available at http://127.0.0.1:5000.
|
||||
Response: `OK`
|
||||
|
||||
### Authentication
|
||||
|
||||
#### Sign Up
|
||||
|
||||
```bash
|
||||
POST /api/signup
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "cyclist",
|
||||
"password": "SecurePass123",
|
||||
"email": "cyclist@example.com",
|
||||
"first_name": "John",
|
||||
"last_name": "Cyclist"
|
||||
}
|
||||
```
|
||||
|
||||
Response:
|
||||
```json
|
||||
{
|
||||
"access_token": "eyJ...",
|
||||
"refresh_token": "eyJ...",
|
||||
"expires_in": 900,
|
||||
"user_id": 1,
|
||||
"username": "cyclist",
|
||||
"email": "cyclist@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
#### Login
|
||||
|
||||
```bash
|
||||
POST /api/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"username": "cyclist",
|
||||
"password": "SecurePass123"
|
||||
}
|
||||
```
|
||||
|
||||
#### Request Password Reset
|
||||
|
||||
```bash
|
||||
POST /api/password-reset/request
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "cyclist@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
#### Confirm Password Reset
|
||||
|
||||
```bash
|
||||
POST /api/password-reset/confirm
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"token": "reset_token_from_email",
|
||||
"new_password": "NewSecurePass123"
|
||||
}
|
||||
```
|
||||
|
||||
#### Logout
|
||||
|
||||
```bash
|
||||
POST /api/logout
|
||||
```
|
||||
|
||||
### Protected Routes
|
||||
|
||||
All protected routes require the `Authorization: Bearer <access_token>` header.
|
||||
|
||||
#### Get User Profile
|
||||
|
||||
```bash
|
||||
GET /api/protected/profile
|
||||
Authorization: Bearer <access_token>
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
Run the test suite:
|
||||
|
||||
```bash
|
||||
chmod +x test-api.sh
|
||||
./test-api.sh
|
||||
```
|
||||
|
||||
This will test:
|
||||
- User signup
|
||||
- Login
|
||||
- Protected routes
|
||||
- Password reset
|
||||
- Error handling
|
||||
|
||||
## Development
|
||||
|
||||
### Running Tests
|
||||
|
||||
To be added.
|
||||
```bash
|
||||
./test-api.sh
|
||||
```
|
||||
|
||||
### Building a New Binary
|
||||
|
||||
```bash
|
||||
go build -o server .
|
||||
```
|
||||
|
||||
### Code Formatting
|
||||
|
||||
```bash
|
||||
go fmt ./...
|
||||
```
|
||||
|
||||
### Linting
|
||||
|
||||
```bash
|
||||
go vet ./...
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Environment Variables for Production
|
||||
|
||||
```env
|
||||
JWT_SECRET_KEY=<generate-secure-random-key>
|
||||
RESEND_API_KEY=<your-resend-production-key>
|
||||
PG_PASSWORD=<strong-database-password>
|
||||
```
|
||||
|
||||
### Building for Production
|
||||
|
||||
```bash
|
||||
./build.sh -t prod --no-cache --run
|
||||
```
|
||||
|
||||
Or push to registry:
|
||||
|
||||
```bash
|
||||
./build.sh -t prod -r docker.io/username --push
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Database Connection Errors
|
||||
|
||||
Ensure PostgreSQL is running and `.env` variables are correct:
|
||||
|
||||
```bash
|
||||
psql -h localhost -U postgres -d rideaware
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
Change the PORT in `.env` or stop the running container:
|
||||
|
||||
```bash
|
||||
podman kill rideaware-api
|
||||
podman rm rideaware-api
|
||||
```
|
||||
|
||||
### Docker Permission Issues
|
||||
|
||||
Run podman with sudo or add your user to the podman group:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG podman $USER
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please create a pull request or open an issue for any improvements or bug fixes.
|
||||
Contributions are welcome! Please:
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push to the branch (`git push origin feature/amazing-feature`)
|
||||
5. Open a Pull Request
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the AGPL-3.0 License.
|
||||
This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
For issues, questions, or suggestions, please open an issue on GitHub or contact the development team.
|
||||
Reference in New Issue
Block a user