|
4 | 4 |
|
5 | 5 | YDB is a free and open project and we appreciate to receive contributions from our community. |
6 | 6 |
|
7 | | -## Development Environment Setup |
8 | | - |
9 | | -### Using Dev Containers (Recommended) |
10 | | - |
11 | | -This repository includes a complete development environment using Docker containers that provides everything you need to start contributing immediately. The devcontainer setup includes: |
12 | | - |
13 | | -- **Python 3.9** development environment with all necessary dependencies |
14 | | -- **YDB server** running locally in a container |
15 | | -- **Pre-configured tools**: Git, GitHub CLI, YDB CLI, and essential Python packages |
16 | | -- **VS Code extensions**: Python development tools, linting, formatting, and debugging support |
17 | | - |
18 | | -#### Prerequisites |
19 | | - |
20 | | -- [Docker](https://www.docker.com/get-started) installed and running |
21 | | -- [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) |
22 | | - |
23 | | -#### Quick Start with Dev Containers |
24 | | - |
25 | | -1. Clone the repository: |
26 | | - ```bash |
27 | | - git clone https://github.com/ydb-platform/ydb-python-sdk.git |
28 | | - cd ydb-python-sdk |
29 | | - ``` |
30 | | - |
31 | | -2. Open in VS Code: |
32 | | - ```bash |
33 | | - code . |
34 | | - ``` |
35 | | - |
36 | | -3. When prompted, click "Reopen in Container" or use the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and select "Dev Containers: Reopen in Container" |
37 | | - |
38 | | -4. Wait for the container to build and start (first time may take a few minutes) |
39 | | - |
40 | | -5. The development environment is ready! You can now run tests, debug code, and develop new features. |
41 | | - |
42 | | -### Using GitHub Codespaces |
43 | | - |
44 | | -GitHub Codespaces provides a cloud-based development environment that works directly in your browser or VS Code. It's perfect for quick contributions without setting up a local environment. |
45 | | - |
46 | | -#### Quick Start with Codespaces |
47 | | - |
48 | | -1. Navigate to the [repository on GitHub](https://github.com/ydb-platform/ydb-python-sdk) |
49 | | -2. Click the green "Code" button |
50 | | -3. Select the "Codespaces" tab |
51 | | -4. Click "Create codespace on main" (or your desired branch) |
52 | | -5. Wait for the environment to initialize (usually 2-3 minutes) |
53 | | -6. Start coding directly in the browser or connect with your local VS Code |
54 | | - |
55 | | -#### What's Included in the Development Environment |
56 | | - |
57 | | -When you use either dev containers or Codespaces, the following environment is automatically set up: |
58 | | - |
59 | | -**Container Services:** |
60 | | -- **SDK Container (`sdk`)**: Your main development environment running Python 3.9 on Debian Bookworm |
61 | | -- **YDB Container (`ydb`)**: Local YDB server (version 25.1) for testing and development |
62 | | - |
63 | | -**Development Tools:** |
64 | | -- **YDB CLI**: Pre-installed and configured to connect to the local YDB instance |
65 | | -- **Python Environment**: All project dependencies installed via `pip install -e .` |
66 | | -- **Git Configuration**: Automatic setup for signed commits (if configured) |
67 | | -- **VS Code Extensions**: Python development stack including linting, formatting, and debugging |
68 | | - |
69 | | -**Network Configuration:** |
70 | | -- **Port 2135**: YDB gRPC with TLS |
71 | | -- **Port 2136**: YDB gRPC without TLS |
72 | | -- **Port 8765**: YDB Monitoring interface |
73 | | -- These ports are automatically forwarded and accessible from your local machine |
74 | | - |
75 | | -**Environment Variables:** |
76 | | -The following environment variables are pre-configured for immediate use: |
77 | | -- `YDB_CONNECTION_STRING=grpc://ydb:2136/local` - Standard connection |
78 | | -- `YDB_CONNECTION_STRING_SECURE=grpcs://ydb:2135/local` - Secure connection |
79 | | -- `YDB_SSL_ROOT_CERTIFICATES_FILE=/ydb_certs/ca.pem` - SSL certificates |
80 | | -- `YDB_STATIC_CREDENTIALS_USER=root` and `YDB_STATIC_CREDENTIALS_PASSWORD=1234` - Test credentials |
81 | | - |
82 | | -**Automatic Setup Process:** |
83 | | -1. **Initialize**: Git configuration for signed commits and user settings |
84 | | -2. **Post-Create**: YDB CLI profile setup and GPG configuration for SSH signing |
85 | | -3. **Post-Start**: Installation of Python dependencies, SDK package, and testing tools (tox) |
86 | | - |
87 | | -#### Running Tests in the Development Environment |
88 | | - |
89 | | -Once your environment is ready, you can run the test suite: |
90 | | - |
91 | | -```bash |
92 | | -# Run all tests |
93 | | -tox |
94 | | - |
95 | | -# Run specific test categories |
96 | | -python -m pytest tests/ |
97 | | - |
98 | | -# Run with specific Python version |
99 | | -tox -e py39 |
100 | | -``` |
101 | | - |
102 | | -#### Connecting to the Local YDB Instance |
103 | | - |
104 | | -The YDB CLI is pre-configured to connect to the local instance: |
105 | | - |
106 | | -```bash |
107 | | -# Run a simple query |
108 | | -echo "SELECT 1;" | ydb |
109 | | - |
110 | | -# Access the web interface |
111 | | -# Open http://localhost:8765 in your browser (when using local dev containers) |
112 | | -# In codespaces you can access it via the provided URL in the terminal output. |
113 | | -``` |
| 7 | +For information about setting up your development environment, please see [BUILD.md](BUILD.md). |
114 | 8 |
|
115 | 9 | ## Contributing code changes |
116 | 10 |
|
|
0 commit comments