Installation Guide

Welcome to the Craft Your Startup Boilerplate documentation! This guide will help you set up the project and get it running using the provided FastAPI + React stack. The boilerplate is designed to streamline development and deployment, using Taskfile, Poetry, and Docker for management.

Once you purchase and download the boilerplate, you'll receive an archive (craftyourstartup-boilerplate.zip). Extract this archive, and inside you'll find the project directory.

Getting Started

Prerequisites

Before you begin, make sure you have the following installed:

• Python 3.11+ (We recommend using pyenv to manage your Python versions)
• Poetry
• Docker
• Taskfile
• Visual Studio Code (VS Code) (Recommended IDE)

Setting Up Python with Pyenv

To ensure you're using the correct Python version, we recommend using pyenv to manage your Python versions. Here's how to set it up:

1. Install pyenv:

Follow the pyenv installation guide to install it on your system.

1. Install Python 3.11:

Once pyenv is installed, use it to install Python 3.11:

pyenv install 3.11.0

1. Set Python 3.11 as the local version:

Inside the project directory, set Python 3.11 as the local version for this project:

pyenv local 3.11.0

This will ensure that whenever you work on this project, Python 3.11 is used.

Setting Up the Project

After setting up Python and extracting the boilerplate archive, follow these steps to set up the project:

1. Navigate to the project directory:

cd craftyourstartup-boilerplate

1. Create environment files:

You'll need to create .env files for both local and production environments. The project includes a local.env.example file to guide you. To set up:

• For local development, create a local.env file:

  cp local.env.example local.env
  

• For production, create a prod.env file (with appropriate production values):

  cp local.env.example prod.env
  

Both of these files should include the following default environment variables (you can modify as needed):

db_username=craftyourstartup
db_password=craftyourstartup
db_host=localhost
db_port=54323
db_database=craftyourstartup
db_sslmode=require
redirect_after_login=http://localhost:5173
[email protected]
aws_access_key_id=xxx
aws_secret_access_key=xxx
google_oauth2_client_id=xxx
google_oauth2_secret=xxx

1. Install project dependencies:

The project uses Poetry for dependency management. Run the following command to install the required Python packages:

task install

1. Start the local database:

To set up the database locally using Docker, run:

task docker-compose

This will start the database container and apply any pending Alembic migrations.

Running the Back-End

You can run the FastAPI back-end in either local or production mode.

• Local environment:

Run the back-end with a local database by executing:

task run-local

This will use local.env to set environment variables and start the FastAPI server on localhost:8012.

• Production environment:

To run the back-end with a production database, use:

task run-prod

This will use prod.env for environment variables.

Alembic Migrations

If you need to manually apply Alembic migrations, run the following task:

task alembic-upgrade-local

This will ensure your local database schema is up-to-date.

Recommended IDE: Visual Studio Code

We recommend using Visual Studio Code (VS Code) for working on this project. VS Code offers excellent support for Python and JavaScript/TypeScript, with a vast array of extensions that will make your development experience smoother. Here's how to set it up:

1. Install the following extensions in VS Code:

2. Python Extension

3. Docker Extension

4. ESLint (for React)

5. Open the project in VS Code

6. Configure Python Interpreter:

   • Poetry will create a virtual environment inside the project directory (usually under ./.venv).
   • Open the command palette (Ctrl + Shift + P) and search for "Python: Select Interpreter".
   • Select the Python interpreter from .venv. It should appear as ./.venv/bin/python.

   This will ensure VS Code uses the virtual environment created by Poetry.

Taskfile Commands

Here's an overview of the available tasks you can run using Taskfile.

Task	Description	Command
install	Installs project dependencies	poetry install
run-local	Runs back-end with local DB	set -o allexport && source local.env && poetry run uvicorn main:app --reload --host localhost --port 8012
run-prod	Runs back-end with prod DB	set -o allexport && source prod.env && poetry run uvicorn main:app --reload --host localhost --port 8012
docker-compose	Sets up and runs the database locally	docker-compose up -d && sleep 2 && task alembic-upgrade-local

Conclusion

That's it! You now have the project set up and running. Make sure you're using Python 3.11+, and we recommend managing your Python versions with pyenv for ease. Don't forget to create your local.env and prod.env based on the provided local.env.example. Also, consider using VS Code for a smoother development experience. If you encounter any problems, feel free to reach out for support. Happy building with Craft Your Startup Boilerplate 🚀!