tkahng / new-ara-api

KAIST Community Ara Renewal Project - KAIST official BBS

SPARCS NewAra API

Restful API for NewAra, KAIST's official community service

Management Information

• Issue tracking: Notion
• Credentials: S3 sparcs-credentials
• Communication: Slack
  • general: #new-ara
  • backend: #new-ara-backend
  • fontend: #new-ara-frontend
  • github commits: #new-ara-noti
  • sentry alerts: #new-ara-sentry
  • notion changes: #new-ara-notion
  • with OB: #ara
• Contact: [e-mail]

Project Setup

Create & Activate Virtual Environment

python3 -m venv env  # should be python 3.8
source env/bin/activate

Install Requirements

pip install poetry
poetry install  # in production - $ poetry install --no-dev
pre-commit install

For macOS, you may need to install openssl & mysqlclient and set LDFLAGS=-L/usr/local/opt/openssl/lib before installing requirements. Only tested for macOS Mojave. See link.

Fill Environment Configuration

Refer to .env.example file and write your own .env file with required informations filled-in. For SPARCS SSO, create a test service or ask SYSOP to deploy production server.

For the test service in SPARCS SSO for local settings, fill in as below.

• Main URL: (can be anything)
• Login Callback URL: http://127.0.0.1:9000/api/users/sso_login_callback/
• Unregister URL: http://127.0.0.1:9000/api/users/sso_unregister/

After this, you should make the information in the .env file as environment variables for local run. (In development or porduction server, we do not use .env file. Rather, we use environment variables in docker-compose.yml file.)

To make the make the information in the .env file as environment variables for local run, you can export each manually, or you can use the below command. Check the Makefile's env command and revise it. The command is written assuming you are using ~/.bashrc. You might want to revise it to ~/.bash_profile or ~/.zshrc according to your settings.

make env

Useful Commands

Most useful commands are already written in the Makefile. Refer to the Makefile and try to understand and use them.

Create and Migrate Database

make init

Collect static files

python manage.py collectstatic

collectstatic command collects all static files required to run installed apps to selected storage - for this project, static S3 bucket. You should open public access for the static bucket to get appropriate response.

Internationalization (i18n)

xgettext is required in order to generate translation files. Detailed background on this can be found on Django's documentations. To generate translation files, run:

make i18n_generate

Translation files are generated under ara/locale/(Locale name)/LC_MESSAGES. After writing translations, run the following command to apply the translations.

make i18n_compile

Create log directory

sudo mkdir -p /var/log/newara
sudo chown $(whoami) /var/log/newara

Run lightweight server for development

make run

0 is abbreviation for 0.0.0.0 which refers to 'listening to every incoming hosts'. Do not deploy with runserver command - use WSGI. This command is only for development.

---

Deployment with Docker

docker-compose.yml

docker-compose.yml file is managed in S3 sparcs-newara bucket docker-compose directory. For simple local deployment, refer to docker-compose.example.yml file and fill in the information needed.

For development server, two docker containsers are up with the docker-compose file. Using AWS RDS for mysql, elastiCache for redis.

• api container (used gunicorn for serving. celery-beat also here.)
• celery-worker container

docker image

For managing docker images, we are using AWS ECR, newara repository.

• Using tag newara:dev for development server.

other docker related files

• Dockerfile: We use virtual environment also inside the docker container.
• .docker/run.sh: api container's entrypoint.
• .docker/run-celery.sh: celery worker container's entrypoint.
• .docker/supervisor-app.conf
• .docker/supervisor-celery-worker.conf

Project Stack

Interpreter

• Python 3.7
• poetry is used as package manager
  • When adding libraries to the virtual environment, you should not use pip. Rather, use poetry add command. Refer to this link for poetry commands.

Framework

• Django 3.2
• djangorestframework 3.14

Database

• MySQL (default)
• mysqlclient 2.1
• django-mysql 3.12

Works with MySQL for Linux & macOS, not tested in Windows. Timezone is automatically adjusted. It is strongly recommended to set default charset of database or MySQL server to utf8mb4.

Storage

• AWS S3
• django-s3-storage 0.13

Two buckets are used - one for storing static files, one for media files that users upload. Go to django-s3-storage documentation for required permissions.

Authentication

• SPARCS SSO v2 API
• djangorestframework SessionAuthentication

API Documentation

• drf-yasg 1.21

---

Contributors

See contributors.