wehub-resource-sync
e071084ebe
govulncheck / govulncheck (push) Has been cancelled
Lint / golangci-lint (push) Has been cancelled
Run Tests / Unit Tests (push) Has been cancelled
Run Tests / Etcd Integration Tests (push) Has been cancelled
Harness (E2E) / Harnesses (mock LLM) (push) Has been cancelled
Harness (E2E) / Provider harnesses (live LLM conformance) (push) Has been cancelled
97 lines
3.3 KiB
Markdown
97 lines
3.3 KiB
Markdown
---
|
|
layout: default
|
|
title: Install troubleshooting
|
|
---
|
|
|
|
# Install troubleshooting
|
|
|
|
Use this page before `micro new` or `micro agent demo` when the CLI install is
|
|
unclear. The goal is to prove three boundaries in order: the `micro` binary is on
|
|
`PATH`, it is the version you expected, and the no-secret first-run path works
|
|
without provider keys.
|
|
|
|
## 1. Choose one install path
|
|
|
|
### Binary installer (no Go required to install)
|
|
|
|
```sh
|
|
curl -fsSL https://go-micro.dev/install.sh | sh
|
|
```
|
|
|
|
Use this when you want the released `micro` binary without building it yourself.
|
|
The generated services still need a Go toolchain when you run `micro run`, but the
|
|
installer itself does not require Go.
|
|
|
|
### Go install (build from source)
|
|
|
|
```sh
|
|
go install go-micro.dev/v6/cmd/micro@latest
|
|
```
|
|
|
|
Use this when Go is already installed and you want the binary in your Go bin
|
|
directory. If the command succeeds but `micro` is not found, your Go bin directory
|
|
is probably not on `PATH`.
|
|
|
|
## 2. Verify `PATH` and version
|
|
|
|
Check which binary your shell will run:
|
|
|
|
```sh
|
|
command -v micro
|
|
micro --version
|
|
```
|
|
|
|
If `command -v micro` prints nothing, add the install directory to `PATH`, then
|
|
open a new terminal and retry. Common locations are:
|
|
|
|
```sh
|
|
export PATH="$HOME/.micro/bin:$PATH" # binary installer
|
|
export PATH="$(go env GOPATH)/bin:$PATH" # go install
|
|
```
|
|
|
|
If `micro --version` shows an older binary than expected, remove the stale copy or
|
|
put the intended install directory earlier in `PATH`.
|
|
|
|
## 3. Run the no-secret smoke path
|
|
|
|
Once `micro` resolves, prove the local service runtime before adding LLM provider
|
|
keys:
|
|
|
|
```sh
|
|
micro new helloworld
|
|
cd helloworld
|
|
micro run
|
|
```
|
|
|
|
In another terminal:
|
|
|
|
```sh
|
|
curl -X POST http://localhost:8080/api/helloworld/Helloworld.Call \
|
|
-H 'Content-Type: application/json' -d '{"name":"World"}'
|
|
```
|
|
|
|
This checks the scaffold, local build, gateway, and service registration without
|
|
calling a model provider.
|
|
|
|
## 4. Recover common failures
|
|
|
|
| Symptom | Check | Fix |
|
|
|---------|-------|-----|
|
|
| `micro: command not found` | `command -v micro` | Add the installer bin directory or `$(go env GOPATH)/bin` to `PATH`, then open a new terminal. |
|
|
| `micro run` cannot find Go | `go version` | Install Go 1.24 or newer from <https://go.dev/doc/install>. |
|
|
| The gateway port is busy | `lsof -i :8080` | Stop the process using the port, or run with a different address. |
|
|
| Provider-key errors block an agent run | `micro agent preflight` | Stay on the no-secret path first: run `micro agent demo`, then the no-secret first-agent guide. |
|
|
|
|
## 5. Continue the first-agent on-ramp
|
|
|
|
After install verification succeeds, continue in order:
|
|
|
|
1. `micro agent demo` — print the provider-free first-agent demo command and next docs steps.
|
|
2. [No-secret first-agent transcript](no-secret-first-agent.html) — prove an agent can use services without a provider key.
|
|
3. [Your First Agent](your-first-agent.html) — build and chat with your own service-backed agent.
|
|
4. [Debugging your agent](debugging-agents.html) — inspect registration, tool calls, run history, and provider failures.
|
|
5. [0→hero Reference](zero-to-hero.html) — walk the full services → agents → workflows lifecycle.
|
|
|
|
For repository contributors, `make install-smoke` runs the same installer seam
|
|
against a local build without network access.
|