|
1 | 1 | # Sim Development Container |
2 | 2 |
|
3 | | -This directory contains configuration files for Visual Studio Code Dev Containers / GitHub Codespaces. Dev containers provide a consistent, isolated development environment for this project. |
| 3 | +Development container configuration for VS Code Dev Containers and GitHub Codespaces. |
4 | 4 |
|
5 | | -## Contents |
| 5 | +## Prerequisites |
6 | 6 |
|
7 | | -- `devcontainer.json` - The main configuration file that defines the development container settings |
8 | | -- `Dockerfile` - Defines the container image and development environment |
9 | | -- `docker-compose.yml` - Sets up the application and database containers |
10 | | -- `post-create.sh` - Script that runs when the container is created |
11 | | -- `.bashrc` - Custom shell configuration with helpful aliases |
| 7 | +- Visual Studio Code |
| 8 | +- Docker Desktop or Podman Desktop |
| 9 | +- VS Code Dev Containers extension |
12 | 10 |
|
13 | | -## Usage |
| 11 | +## Getting Started |
14 | 12 |
|
15 | | -### Prerequisites |
| 13 | +1. Open this project in VS Code |
| 14 | +2. Click "Reopen in Container" when prompted (or press `F1` → "Dev Containers: Reopen in Container") |
| 15 | +3. Wait for the container to build and initialize |
| 16 | +4. Start developing with `sim-start` |
16 | 17 |
|
17 | | -- Visual Studio Code |
18 | | -- Docker installation: |
19 | | - - Docker Desktop (Windows/macOS) |
20 | | - - Docker Engine (Linux) |
21 | | -- VS Code Remote - Containers extension |
| 18 | +The setup script will automatically install dependencies and run migrations. |
22 | 19 |
|
23 | | -### Getting Started |
| 20 | +## Development Commands |
24 | 21 |
|
25 | | -1. Open this project in Visual Studio Code |
26 | | -2. When prompted, click "Reopen in Container" |
27 | | - - Alternatively, press `F1` and select "Remote-Containers: Reopen in Container" |
28 | | -3. Wait for the container to build and initialize |
29 | | -4. The post-creation script will automatically: |
| 22 | +### Running Services |
30 | 23 |
|
31 | | - - Install dependencies |
32 | | - - Set up environment variables |
33 | | - - Run database migrations |
34 | | - - Configure helpful aliases |
| 24 | +You have two options for running the development environment: |
35 | 25 |
|
36 | | -5. Start the application with `sim-start` (alias for `bun run dev`) |
| 26 | +**Option 1: Run everything together (recommended for most development)** |
| 27 | +```bash |
| 28 | +sim-start # Runs both app and socket server using concurrently |
| 29 | +``` |
37 | 30 |
|
38 | | -### Development Commands |
| 31 | +**Option 2: Run services separately (useful for debugging individual services)** |
| 32 | +- In the **app** container terminal: `sim-app` (starts Next.js app on port 3000) |
| 33 | +- In the **realtime** container terminal: `sim-sockets` (starts socket server on port 3002) |
39 | 34 |
|
40 | | -The development environment includes these helpful aliases: |
| 35 | +### Other Commands |
41 | 36 |
|
42 | | -- `sim-start` - Start the development server |
43 | 37 | - `sim-migrate` - Push schema changes to the database |
44 | 38 | - `sim-generate` - Generate new migrations |
45 | | -- `sim-rebuild` - Build and start the production version |
46 | | -- `pgc` - Connect to the PostgreSQL database |
47 | | -- `check-db` - List all databases |
| 39 | +- `build` - Build the application |
| 40 | +- `pgc` - Connect to PostgreSQL database |
48 | 41 |
|
49 | | -### Using GitHub Codespaces |
| 42 | +## Troubleshooting |
50 | 43 |
|
51 | | -This project is also configured for GitHub Codespaces. To use it: |
| 44 | +**Build errors**: Rebuild the container with `F1` → "Dev Containers: Rebuild Container" |
52 | 45 |
|
53 | | -1. Go to the GitHub repository |
54 | | -2. Click the "Code" button |
55 | | -3. Select the "Codespaces" tab |
56 | | -4. Click "Create codespace on main" |
| 46 | +**Port conflicts**: Ensure ports 3000, 3002, and 5432 are available |
57 | 47 |
|
58 | | -This will start a new Codespace with the development environment already set up. |
| 48 | +**Container runtime issues**: Verify Docker Desktop or Podman Desktop is running |
59 | 49 |
|
60 | | -## Customization |
| 50 | +## Technical Details |
61 | 51 |
|
62 | | -You can customize the development environment by: |
| 52 | +Services: |
| 53 | +- **App container** (8GB memory limit) - Main Next.js application |
| 54 | +- **Realtime container** (4GB memory limit) - Socket.io server for real-time features |
| 55 | +- **Database** - PostgreSQL with pgvector extension |
| 56 | +- **Migrations** - Runs automatically on container creation |
63 | 57 |
|
64 | | -- Modifying `devcontainer.json` to add VS Code extensions or settings |
65 | | -- Updating the `Dockerfile` to install additional packages |
66 | | -- Editing `docker-compose.yml` to add services or change configuration |
67 | | -- Modifying `.bashrc` to add custom aliases or configurations |
| 58 | +You can develop with services running together or independently. |
68 | 59 |
|
69 | | -## Troubleshooting |
| 60 | +### Personalization |
70 | 61 |
|
71 | | -If you encounter issues: |
| 62 | +**Project commands** (`sim-start`, `sim-app`, etc.) are automatically available via `/workspace/.devcontainer/sim-commands.sh`. |
72 | 63 |
|
73 | | -1. Rebuild the container: `F1` → "Remote-Containers: Rebuild Container" |
74 | | -2. Check Docker logs for build errors |
75 | | -3. Verify Docker Desktop is running |
76 | | -4. Ensure all prerequisites are installed |
| 64 | +**Personal shell customization** (aliases, prompts, etc.) should use VS Code's dotfiles feature: |
| 65 | +1. Create a dotfiles repository (e.g., `github.com/youruser/dotfiles`) |
| 66 | +2. Add your `.bashrc`, `.zshrc`, or other configs |
| 67 | +3. Configure in VS Code Settings: |
| 68 | + ```json |
| 69 | + { |
| 70 | + "dotfiles.repository": "youruser/dotfiles", |
| 71 | + "dotfiles.installCommand": "install.sh" |
| 72 | + } |
| 73 | + ``` |
77 | 74 |
|
78 | | -For more information, see the [VS Code Remote Development documentation](https://code.visualstudio.com/docs/remote/containers). |
| 75 | +This separates project-specific commands from personal preferences, following VS Code best practices. |
0 commit comments