Skip to content

Commit

Permalink
refactor contributing guidelines into a separate file, add open-sourc…
Browse files Browse the repository at this point in the history 
…e headers
  • Loading branch information
@codekansas
codekansas committed Jun 10, 2024
1 parent 01e24e6 commit 35213be
Show file tree
Hide file tree
Showing 2 changed files with 164 additions and 142 deletions.
144 changes: 144 additions & 0 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
# Development

To get started developing:

1. Clone the repository
2. Install the React dependencies and create a `.env.local` file
3. Install the FastAPI dependencies
4. Start the Redis and DynamoDB databases
5. Initialize the test databases
6. Serve the FastAPI application
7. Serve the React frontend

## Database

### DynamoDB

When developing locally, use the `amazon/dynamodb-local` Docker image to run a local instance of DynamoDB:

```bash
docker pull amazon/dynamodb-local # If you haven't already
docker run --name store-db -d -p 8000:8000 amazon/dynamodb-local # Start the container in the background
```

Then, if you need to kill the database, you can run:

```bash
docker kill store-db || true
docker rm store-db || true
```

Initialize the test databases by running the creation script:

```bash
python -m store.app.db create
```

#### Admin Panel

DynamoDB Admin is a GUI that allows you to visually see your tables and their entries. To install, run

```bash
npm i -g dynamodb-admin
```

To run, **source the same environment variables that you use for FastAPI** and then run

```bash
dynamodb-admin
```

### Redis

For Redis, use the `redis` Docker image:

```bash
docker pull redis # If you haven't already
docker run --name store-redis -d -p 6379:6379 redis # Start the container in the background
```

Then, if you need to kill the database, you can run:

```bash
docker kill store-redis || true
docker rm store-redis || true
```

## FastAPI

Create a Python virtual environment using either [uv](https://astral.sh/blog/uv) or [virtualenv](https://virtualenv.pypa.io/en/latest/) with at least Python 3.11. This should look something like this:

```bash
uv venv .venv --python 3.11 # If using uv
python -m venv .venv # Using vanilla virtualenv
source .venv/bin/activate
```

Install the project:

```bash
uv pip install -e '.[dev]' # If using uv
pip install -e '.[dev]' # Using vanilla pip
```

Serve the FastAPI application in development mode:

```bash
fastapi dev 'store/app/main.py' --port 8080 # On port 8080 to avoid conflicts with Docker
```

### Configuration

Settings for the app backend live in the `store/settings/` directory. You can use the following environment variables:

- `ROBOLIST_ENVIRONMENT_SECRETS` should be the path to a local `.env` file containing any environment secrets
- `ROBOLIST_ENVIRONMENT` is the stem of one of the config files in the `store/settings/configs/` directory. When developing locally this should usually just be `local`

To locally develop, setting the following environment variables will work (presuming you have set everything else up):

```
export ROBOLIST_ENVIRONMENT=local
export ROBOLIST_ENVIRONMENT_SECRETS=.env
export AWS_DEFAULT_REGION='us-east-1'
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export REACT_APP_BACKEND_URL=http://127.0.0.1:8080
```

## React

To install the React dependencies, use [nvm](https://github.com/nvm-sh/nvm) and [npm](https://www.npmjs.com/):

```bash
cd frontend
nvm use 20.10.0
npm install
```

To serve the React frontend in development mode:

```bash
npm start
```

To build the React frontend for production:

```bash
npm run build
```

To run code formatting:

```bash
npm run format
```

### Environment Variables

You will need to set `REACT_APP_GOOGLE_CLIENT_ID`. To do this, first create a Google client id (see [this LogRocket post](https://blog.logrocket.com/guide-adding-google-login-react-app/)). Then create a `.env.local` file in the `frontend` directory and add the following line:

```
REACT_APP_GOOGLE_CLIENT_ID=your-client-id
```

Additionally, you should set `REACT_APP_BACKEND_URL` to the URL of the FastAPI backend. This should be `http://127.0.0.1:8080` when developing locally.
162 changes: 20 additions & 142 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,148 +1,26 @@
# store
<p align="center">
<picture>
<img alt="K-Scale Open Source Robotics" src="https://media.kscale.dev/kscale-open-source-header.png" style="max-width: 100%;">
</picture>
</p>

This is the code for our online store. This is a simple store for buying and selling humanoid robots.
<div align="center">

## Development
[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/kscalelabs/ksim/blob/main/LICENSE)
[![Discord](https://img.shields.io/discord/1224056091017478166)](https://discord.gg/k5mSvCkYQh)
[![Wiki](https://img.shields.io/badge/wiki-humanoids-black)](https://humanoids.wiki)
<br />
[![python](https://img.shields.io/badge/-Python_3.11-blue?logo=python&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![black](https://img.shields.io/badge/Code%20Style-Black-black.svg?labelColor=gray)](https://black.readthedocs.io/en/stable/)
[![ruff](https://img.shields.io/badge/Linter-Ruff-red.svg?labelColor=gray)](https://github.com/charliermarsh/ruff)
<br />
[![CI Checks (Linting and Tests)](https://github.com/kscalelabs/store/actions/workflows/test.yml/badge.svg)](https://github.com/kscalelabs/store/actions/workflows/test.yml)
[![Deploys latest code](https://github.com/kscalelabs/store/actions/workflows/deploy.yml/badge.svg)](https://github.com/kscalelabs/store/actions/workflows/deploy.yml)

To get started developing:
</div>

1. Clone the repository
2. Install the React dependencies and create a `.env.local` file
3. Install the FastAPI dependencies
4. Start the Redis and DynamoDB databases
5. Initialize the test databases
6. Serve the FastAPI application
7. Serve the React frontend
# RoboList

### Database
This is the code for our online store. This is a simple store for buying and selling robots and robot parts.

#### DynamoDB

When developing locally, use the `amazon/dynamodb-local` Docker image to run a local instance of DynamoDB:

```bash
docker pull amazon/dynamodb-local # If you haven't already
docker run --name store-db -d -p 8000:8000 amazon/dynamodb-local # Start the container in the background
```

Then, if you need to kill the database, you can run:

```bash
docker kill store-db || true
docker rm store-db || true
```

Initialize the test databases by running the creation script:

```bash
python -m store.app.db create
```

##### Admin Panel

DynamoDB Admin is a GUI that allows you to visually see your tables and their entries. To install, run

```bash
npm i -g dynamodb-admin
```

To run, **source the same environment variables that you use for FastAPI** and then run

```bash
dynamodb-admin
```

#### Redis

For Redis, use the `redis` Docker image:

```bash
docker pull redis # If you haven't already
docker run --name store-redis -d -p 6379:6379 redis # Start the container in the background
```

Then, if you need to kill the database, you can run:

```bash
docker kill store-redis || true
docker rm store-redis || true
```

### FastAPI

Create a Python virtual environment using either [uv](https://astral.sh/blog/uv) or [virtualenv](https://virtualenv.pypa.io/en/latest/) with at least Python 3.11. This should look something like this:

```bash
uv venv .venv --python 3.11 # If using uv
python -m venv .venv # Using vanilla virtualenv
source .venv/bin/activate
```

Install the project:

```bash
uv pip install -e '.[dev]' # If using uv
pip install -e '.[dev]' # Using vanilla pip
```

Serve the FastAPI application in development mode:

```bash
fastapi dev 'store/app/main.py' --port 8080 # On port 8080 to avoid conflicts with Docker
```

#### Configuration

Settings for the app backend live in the `store/settings/` directory. You can use the following environment variables:

- `ROBOLIST_ENVIRONMENT_SECRETS` should be the path to a local `.env` file containing any environment secrets
- `ROBOLIST_ENVIRONMENT` is the stem of one of the config files in the `store/settings/configs/` directory. When developing locally this should usually just be `local`

To locally develop, setting the following environment variables will work (presuming you have set everything else up):

```
export ROBOLIST_ENVIRONMENT=local
export ROBOLIST_ENVIRONMENT_SECRETS=.env
export AWS_DEFAULT_REGION='us-east-1'
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export REACT_APP_BACKEND_URL=http://127.0.0.1:8080
```

### React

To install the React dependencies, use [nvm](https://github.com/nvm-sh/nvm) and [npm](https://www.npmjs.com/):

```bash
cd frontend
nvm use 20.10.0
npm install
```

To serve the React frontend in development mode:

```bash
npm start
```

To build the React frontend for production:

```bash
npm run build
```

To run code formatting:

```bash
npm run format
```

#### Environment Variables

You will need to set `REACT_APP_GOOGLE_CLIENT_ID`. To do this, first create a Google client id (see [this LogRocket post](https://blog.logrocket.com/guide-adding-google-login-react-app/)). Then create a `.env.local` file in the `frontend` directory and add the following line:

```
REACT_APP_GOOGLE_CLIENT_ID=your-client-id
```

Additionally, you should set `REACT_APP_BACKEND_URL` to the URL of the FastAPI backend. This should be `http://127.0.0.1:8080` when developing locally.
If you would like to contribute, see the [CONTRIBUTING.md](CONTRIBUTING.md) file.

0 comments on commit 35213be

Please sign in to comment.