rg_backend_academy/README.md

# RG Backend Academy

Educational full-stack project for learning backend development with Node.js, React, and a local PostgreSQL database.

The repository is intentionally small at the moment. Use this document as the baseline environment guide before adding the backend, frontend, database schema, tests, and deployment notes.

## Planned stack

- Node.js 22 LTS or newer
- npm, pnpm, or another package manager selected by the project
- React for the frontend application
- PostgreSQL running locally on Ubuntu
- Git for version control

## Ubuntu environment setup

The commands below target Ubuntu or Ubuntu-based Linux distributions.

### 1. Install system dependencies

```bash
sudo apt update
sudo apt install -y curl ca-certificates gnupg git build-essential postgresql postgresql-contrib
```

### 2. Install Node.js 22 with nvm

Using `nvm` keeps the project Node.js version isolated from the system installation.

```bash
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
```

Restart the terminal, then install and use Node.js 22:

```bash
nvm install 22
nvm use 22
node --version
npm --version
```

Expected Node.js version:

```text
v22.x.x
```

This repository includes a `.nvmrc` file, so later terminal sessions can use:

```bash
nvm use
```

### 3. Start PostgreSQL

```bash
sudo systemctl enable --now postgresql
sudo systemctl status postgresql
```

### 4. Create a local development database

Use a dedicated application user instead of the default `postgres` superuser.

```bash
sudo -u postgres psql
```

Inside the PostgreSQL shell:

```sql
CREATE USER rg_academy WITH PASSWORD 'rg_academy';
CREATE DATABASE rg_academy_dev OWNER rg_academy;
GRANT ALL PRIVILEGES ON DATABASE rg_academy_dev TO rg_academy;
\q
```

Test the connection:

```bash
psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
```

Exit with:

```sql
\q
```

### 5. Environment variables

When the backend application is added, create a local `.env` file from the provided example file.

Expected baseline variables:

```bash
DATABASE_URL="postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
NODE_ENV="development"
```

Do not commit `.env` files with secrets or local credentials.

## Suggested repository structure

The exact structure may evolve, but this is the recommended starting point:

```text
.
├── apps
│   ├── backend
│   └── web
├── packages
│   └── shared
├── docs
├── README.md
└── AGENTS.md
```

## Development workflow

After the project code is added, the usual local workflow should be:

```bash
nvm use
npm install
npm run dev
```

Recommended scripts to add once the application exists:

- `npm run dev` - start local backend and frontend development servers.
- `npm run test` - run automated tests.
- `npm run lint` - run static checks.
- `npm run format` - format source files.
- `npm run db:migrate` - apply database migrations.
- `npm run db:seed` - seed local development data.

## PostgreSQL quick reference

Open the project database:

```bash
psql "postgresql://rg_academy:rg_academy@localhost:5432/rg_academy_dev"
```

List databases:

```sql
\l
```

List tables:

```sql
\dt
```

Describe a table:

```sql
\d table_name
```

## Troubleshooting

Check whether PostgreSQL is running:

```bash
sudo systemctl status postgresql
```

Restart PostgreSQL:

```bash
sudo systemctl restart postgresql
```

Check the installed Node.js version:

```bash
node --version
```

If `psql` cannot connect, verify that PostgreSQL is listening locally and that the database URL matches the user, password, host, port, and database name.

## Documentation rules

- Project documentation is written in English.
- Code comments are written in English.
- User-facing chat responses for this project should be in Czech unless the user asks otherwise.

## Codex

Use Codex from the repository root so it can read `README.md`, `AGENTS.md`, and the local project files.

Start a new Codex session:

```bash
npx @openai/codex --no-alt-screen -s workspace-write
```

Resume an existing Codex session:

```bash
npx @openai/codex resume <session-id> --no-alt-screen -s workspace-write
```

For repository-specific agent behavior, see `AGENTS.md`.

## Local AI coding setup

The following optional setup provides local coding assistance on Kubuntu or Ubuntu with Ollama, Aider, and the Continue extension for VS Code.

### Ollama

Install Ollama:

```bash
curl -fsSL https://ollama.com/install.sh | sh
sudo systemctl status ollama
```

Download the recommended local models:

```bash
ollama pull qwen2.5-coder:1.5b-base
ollama pull qwen2.5-coder:7b
ollama pull qwen2.5-coder:14b
ollama pull nomic-embed-text
```

Verify that the Ollama API is available:

```bash
curl http://127.0.0.1:11434/api/tags
```

Recommended model usage:

| Use case | Model |
| --- | --- |
| Autocomplete | `qwen2.5-coder:1.5b-base` |
| Daily coding | `qwen2.5-coder:7b` |
| Larger refactoring and review | `qwen2.5-coder:14b` |
| Embeddings | `nomic-embed-text` |

### Aider

Install Aider with `uv`:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
uv tool install aider-chat
```

Configure the local Ollama endpoint and optional aliases:

```bash
echo 'export OLLAMA_API_BASE=http://127.0.0.1:11434' >> ~/.bashrc
echo 'alias aider7="aider --model ollama_chat/qwen2.5-coder:7b"' >> ~/.bashrc
echo 'alias aider14="aider --model ollama_chat/qwen2.5-coder:14b"' >> ~/.bashrc
source ~/.bashrc
```

Start Aider from the repository root:

```bash
cd <project>
aider7
```

Ollama must be running locally on port `11434`. Aider works best inside a Git repository and may ask to add its local files to `.gitignore`.

### Continue for VS Code

Install the Continue extension from the VS Code extension view or with:

```bash
code --install-extension Continue.continue
```

Open the command palette with `Ctrl+Shift+P`, run `Continue: Open Config`, and use:

```yaml
name: Local Ollama Coding
version: 0.0.1
schema: v1

models:
  - name: Qwen Coder 7B
    provider: ollama
    model: qwen2.5-coder:7b
    roles:
      - chat
      - edit
      - apply

  - name: Qwen Coder 1.5B
    provider: ollama
    model: qwen2.5-coder:1.5b-base
    roles:
      - autocomplete

  - name: Nomic Embeddings
    provider: ollama
    model: nomic-embed-text
    roles:
      - embed
```

Enable Continue tab autocomplete in the VS Code settings. Use Aider with Ollama for project-wide terminal changes, Continue for editor navigation and autocomplete, and Codex for larger repository tasks.