Skip to content

Commit ce33b7e

Browse files
LocalAI [bot]localai-botmudler
authored
docs: add comprehensive development setup instructions to CONTRIBUTING.md (H7) (mudler#8860)
* docs: add comprehensive development setup instructions to CONTRIBUTING.md - Expand prerequisites with Go version requirements and installation links - Add system dependencies for Ubuntu/Debian, CentOS/RHEL/Fedora, macOS, and Windows - Document build commands with explanations and key build variables - Add environment variables section with useful development env vars - Include development workflow guidelines (branch naming, commit format, PR process) - Enhance testing section with per-package and focused test instructions * Apply suggestions from code review Signed-off-by: Ettore Di Giacinto <mudler@users.noreply.github.com> --------- Signed-off-by: Ettore Di Giacinto <mudler@users.noreply.github.com> Co-authored-by: localai-bot <localai-bot@noreply.github.com> Co-authored-by: Ettore Di Giacinto <mudler@users.noreply.github.com>
1 parent 9090bca commit ce33b7e

1 file changed

Lines changed: 186 additions & 20 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 186 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,10 @@ Thank you for your interest in contributing to LocalAI! We appreciate your time
77
- [Getting Started](#getting-started)
88
- [Prerequisites](#prerequisites)
99
- [Setting up the Development Environment](#setting-up-the-development-environment)
10+
- [Environment Variables](#environment-variables)
1011
- [Contributing](#contributing)
1112
- [Submitting an Issue](#submitting-an-issue)
13+
- [Development Workflow](#development-workflow)
1214
- [Creating a Pull Request (PR)](#creating-a-pull-request-pr)
1315
- [Coding Guidelines](#coding-guidelines)
1416
- [Testing](#testing)
@@ -19,18 +21,122 @@ Thank you for your interest in contributing to LocalAI! We appreciate your time
1921

2022
### Prerequisites
2123

22-
- Golang [1.21]
23-
- Git
24-
- macOS/Linux
24+
- **Go 1.21+** (the project currently uses Go 1.26 in `go.mod`, but 1.21 is the minimum supported version)
25+
- [Download Go](https://go.dev/dl/) or install via your package manager
26+
- macOS: `brew install go`
27+
- Ubuntu/Debian: follow the [official instructions](https://go.dev/doc/install) (the `apt` version is often outdated)
28+
- Verify: `go version`
29+
- **Git**
30+
- **GNU Make**
31+
- **GCC / C/C++ toolchain** (required for CGo and native backends)
32+
- **Protocol Buffers compiler** (`protoc`) — needed for gRPC code generation
2533

26-
### Setting up the Development Environment and running localAI in the local environment
34+
#### System dependencies by platform
2735

28-
1. Clone the repository: `git clone https://github.com/go-skynet/LocalAI.git`
29-
2. Navigate to the project directory: `cd LocalAI`
30-
3. Install the required dependencies ( see https://localai.io/basics/build/#build-localai-locally )
31-
4. Build LocalAI: `make build`
32-
5. Run LocalAI: `./local-ai`
33-
6. To Build and live reload: `make build-dev`
36+
<details>
37+
<summary><strong>Ubuntu / Debian</strong></summary>
38+
39+
```bash
40+
sudo apt-get update
41+
sudo apt-get install -y build-essential gcc g++ cmake git wget \
42+
protobuf-compiler libprotobuf-dev pkg-config \
43+
libopencv-dev libgrpc-dev
44+
```
45+
46+
</details>
47+
48+
<details>
49+
<summary><strong>CentOS / RHEL / Fedora</strong></summary>
50+
51+
```bash
52+
sudo dnf groupinstall -y "Development Tools"
53+
sudo dnf install -y cmake git wget protobuf-compiler protobuf-devel \
54+
opencv-devel grpc-devel
55+
```
56+
57+
</details>
58+
59+
<details>
60+
<summary><strong>macOS</strong></summary>
61+
62+
```bash
63+
xcode-select --install
64+
brew install cmake git protobuf grpc opencv wget
65+
```
66+
67+
</details>
68+
69+
<details>
70+
<summary><strong>Windows</strong></summary>
71+
72+
Use [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install) with an Ubuntu distribution, then follow the Ubuntu instructions above.
73+
74+
</details>
75+
76+
### Setting up the Development Environment
77+
78+
1. **Clone the repository:**
79+
80+
```bash
81+
git clone https://github.com/mudler/LocalAI.git
82+
cd LocalAI
83+
```
84+
85+
2. **Build LocalAI:**
86+
87+
```bash
88+
make build
89+
```
90+
91+
This runs protobuf generation, installs Go tools, builds the React UI, and compiles the `local-ai` binary. Key build variables you can set:
92+
93+
| Variable | Description | Example |
94+
|---|---|---|
95+
| `BUILD_TYPE` | GPU/accelerator type (`cublas`, `hipblas`, `intel`, ``) | `BUILD_TYPE=cublas make build` |
96+
| `GO_TAGS` | Additional Go build tags | `GO_TAGS=debug make build` |
97+
| `CUDA_MAJOR_VERSION` | CUDA major version (default: `13`) | `CUDA_MAJOR_VERSION=12` |
98+
99+
3. **Run LocalAI:**
100+
101+
```bash
102+
./local-ai
103+
```
104+
105+
4. **Development mode with live reload:**
106+
107+
```bash
108+
make build-dev
109+
```
110+
111+
This installs [`air`](https://github.com/air-verse/air) automatically and watches for file changes, rebuilding and restarting the server on each save.
112+
113+
5. **Containerized build** (no local toolchain needed):
114+
115+
```bash
116+
make docker
117+
```
118+
119+
For GPU-specific Docker builds, see the `docker-build-*` targets in the Makefile and refer to [CLAUDE.md](CLAUDE.md) for detailed backend build instructions.
120+
121+
### Environment Variables
122+
123+
LocalAI is configured primarily through environment variables (or equivalent CLI flags). The most useful ones for development are:
124+
125+
| Variable | Description | Default |
126+
|---|---|---|
127+
| `LOCALAI_DEBUG` | Enable debug mode | `false` |
128+
| `LOCALAI_LOG_LEVEL` | Log verbosity (`error`, `warn`, `info`, `debug`, `trace`) | — |
129+
| `LOCALAI_LOG_FORMAT` | Log format (`default`, `text`, `json`) | `default` |
130+
| `LOCALAI_MODELS_PATH` | Path to model files | `./models` |
131+
| `LOCALAI_BACKENDS_PATH` | Path to backend binaries | `./backends` |
132+
| `LOCALAI_CONFIG_DIR` | Directory for dynamic config files (API keys, external backends) | `./configuration` |
133+
| `LOCALAI_THREADS` | Number of threads for inference | — |
134+
| `LOCALAI_ADDRESS` | Bind address for the API server | `:8080` |
135+
| `LOCALAI_API_KEY` | API key(s) for authentication | — |
136+
| `LOCALAI_CORS` | Enable CORS | `false` |
137+
| `LOCALAI_DISABLE_WEBUI` | Disable the web UI | `false` |
138+
139+
See `core/cli/run.go` for the full list of supported environment variables.
34140

35141
## Contributing
36142

@@ -40,18 +146,40 @@ We welcome contributions from everyone! To get started, follow these steps:
40146

41147
If you find a bug, have a feature request, or encounter any issues, please check the [issue tracker](https://github.com/go-skynet/LocalAI/issues) to see if a similar issue has already been reported. If not, feel free to [create a new issue](https://github.com/go-skynet/LocalAI/issues/new) and provide as much detail as possible.
42148

43-
### Creating a Pull Request (PR)
149+
### Development Workflow
150+
151+
#### Branch naming conventions
152+
153+
Use a descriptive branch name that indicates the type and scope of the change:
154+
155+
- `feature/<short-description>` — new functionality
156+
- `fix/<short-description>` — bug fixes
157+
- `docs/<short-description>` — documentation changes
158+
- `refactor/<short-description>` — code refactoring
159+
160+
#### Commit messages
161+
162+
- Use a short, imperative subject line (e.g., "feat: add whisper backend support", not "Added whisper backend support")
163+
- Keep the subject under 72 characters
164+
- Use the body to explain **why** the change was made when the subject alone is not sufficient
165+
- Use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
166+
167+
#### Creating a Pull Request (PR)
44168

45169
Before jumping into a PR for a massive feature or big change, it is preferred to discuss it first via an issue.
46170

47171
1. Fork the repository.
48-
2. Create a new branch with a descriptive name: `git checkout -b [branch name]`
49-
3. Make your changes and commit them.
50-
4. Push the changes to your fork: `git push origin [branch name]`
51-
5. Create a new pull request from your branch to the main project's `main` or `master` branch.
52-
6. Provide a clear description of your changes in the pull request.
53-
7. Make any requested changes during the review process.
54-
8. Once your PR is approved, it will be merged into the main project.
172+
2. Create a new branch: `git checkout -b feature/my-change`
173+
3. Make your changes, keeping commits focused and atomic.
174+
4. Run tests locally before pushing (see [Testing](#testing) below).
175+
5. Push to your fork: `git push origin feature/my-change`
176+
6. Open a pull request against the `master` branch.
177+
7. Fill in the PR description with:
178+
- What the change does and why
179+
- How it was tested
180+
- Any breaking changes or migration steps
181+
8. Respond to review feedback promptly. Push follow-up commits rather than force-pushing amended commits so reviewers can see incremental changes.
182+
9. Once approved, a maintainer will merge your PR.
55183

56184
## Coding Guidelines
57185

@@ -85,11 +213,40 @@ For AI-assisted development, see [`CLAUDE.md`](CLAUDE.md) for agent-specific gui
85213

86214
## Testing
87215

88-
`make test` cannot handle all the model now. Please be sure to add a test case for the new features or the part was changed.
216+
All new features and bug fixes should include test coverage. The project uses [Ginkgo](https://onsi.github.io/ginkgo/) as its test framework.
217+
218+
### Running unit tests
219+
220+
```bash
221+
make test
222+
```
223+
224+
This downloads test model fixtures, runs protobuf generation, and executes the full test suite including llama-gguf, TTS, and stable-diffusion tests. Note: some tests require model files to be downloaded, so the first run may take longer.
225+
226+
To run tests for a specific package:
227+
228+
```bash
229+
go test ./core/config/...
230+
go test ./pkg/model/...
231+
```
232+
233+
To run a specific test by name using Ginkgo's `--focus` flag:
234+
235+
```bash
236+
go run github.com/onsi/ginkgo/v2/ginkgo --focus="should load a model" -v -r ./core/
237+
```
238+
239+
### Running end-to-end tests
240+
241+
The e2e tests run LocalAI in a Docker container and exercise the API:
242+
243+
```bash
244+
make test-e2e
245+
```
89246

90247
### Running AIO tests
91248

92-
All-In-One images has a set of tests that automatically verifies that most of the endpoints works correctly, a flow can be :
249+
All-In-One images have a set of tests that automatically verify that most of the endpoints work correctly:
93250

94251
```bash
95252
# Build the LocalAI docker image
@@ -102,6 +259,15 @@ BASE_IMAGE=local-ai DOCKER_AIO_IMAGE=local-ai-aio:test make docker-aio
102259
LOCALAI_IMAGE_TAG=test LOCALAI_IMAGE=local-ai-aio make run-e2e-aio
103260
```
104261

262+
### Testing backends
263+
264+
To prepare and test extra (Python) backends:
265+
266+
```bash
267+
make prepare-test-extra # build Python backends for testing
268+
make test-extra # run backend-specific tests
269+
```
270+
105271
## Documentation
106272

107273
We are welcome the contribution of the documents, please open new PR or create a new issue. The documentation is available under `docs/` https://github.com/mudler/LocalAI/tree/master/docs

0 commit comments

Comments
 (0)