122 lines
4.0 KiB
Markdown
122 lines
4.0 KiB
Markdown
# ⚡️ GoShort
|
|
|
|
### Self-host your own URL shortener!
|
|
|
|
|
|
|
|
|
|
|
|
[More screenshots/videos](.github/assets/)
|
|
|
|
---
|
|
## Features
|
|
- **⚡️ Fast**: <10ms response times at 500 rps
|
|
- **🪶 Light**:
|
|
- **0% CPU and 10MB memory** usage at idle
|
|
- **2% CPU and 15MB memory** usage at 500 rps
|
|
- **🐳 Easy**: Single 17MB binary / 20MB Docker image
|
|
- **🔐 Private**: Enable or disable registrations
|
|
- **🍰 Simple**: In-memory or SQLite databases
|
|
|
|
## Quick start
|
|
```bash
|
|
docker run \
|
|
-p 8080:8080 \
|
|
git.maronato.dev/maronato/goshort:latest
|
|
```
|
|
|
|
Or via Docker Compose:
|
|
```yml
|
|
service:
|
|
goshort:
|
|
image: git.maronato.dev/maronato/goshort:latest
|
|
ports:
|
|
- 8080:8080
|
|
```
|
|
|
|
Then open [http://localhost:8080](http://localhost:8080)
|
|
|
|
If you want to persist the database, attach a volume to `/app`:
|
|
```bash
|
|
docker run \
|
|
-p 8080:8080 \
|
|
-v /path/to/db:/app /
|
|
git.maronato.dev/maronato/goshort:latest
|
|
```
|
|
|
|
Or via Docker Compose:
|
|
```yml
|
|
service:
|
|
goshort:
|
|
image: git.maronato.dev/maronato/goshort:latest
|
|
ports:
|
|
- 8080:8080
|
|
volumes:
|
|
- /path/to/db:/app
|
|
```
|
|
|
|
## Config
|
|
|
|
You can configure GoShort using command line flags and environment variables.
|
|
|
|
| Option | type | Flag | Env | Default |
|
|
| ------------------------ | -------------------- | ------------------------- | ---------------------------- | -------------------------------------------------------- |
|
|
| Start in production mode | `boolean` | -prod | GOSHORT_PROD | `false` when running the binary, `true` in Docker |
|
|
| Debug mode | `boolean` | -debug | GOSHORT_DEBUG | `false` |
|
|
| Bind address | address | -host <value> | GOSHORT_HOST | `localhost` when running the binary, `0.0.0.0` in Docker |
|
|
| Bind port | `integer` | -port <value> | GOSHORT_PORT | `8080` |
|
|
| DB type | `memory` or `sqlite` | -db-type <value> | GOSHORT_DB_TYPE | `sqlite` |
|
|
| DB URL/Path | path | -db <value> | GOSHORT_DB | `goshort.db` |
|
|
| Session duration | duration | -session-duration <value> | GOSHORT_SESSION_DURATION | 7 days |
|
|
| Disable registrations | `boolean` | -disable-registration | GOSHORT_DISABLE_REGISTRATION | `false` |
|
|
|
|
|
|
## Healthchecks
|
|
The docker image has health checks enabled by default. They are done via a subcommand that pings the `/healthz` endpoint and fails when it returns a bad value.
|
|
|
|
You can use the same endpoint to perform health checks manually.
|
|
|
|
> Important! If you use Docker or Compose, prefer defining the `GOSHORT_HOST` and `GOSHORT_PORT` configs as environment variables instead of command line flags.
|
|
> They are used by the healthcheck command to find the address to call, so it's important that they are synced between the main process and the healthcheck.
|
|
|
|
## Building and running from source
|
|
You'll need:
|
|
- Go 1.21 or greater
|
|
- Node 18 or greater
|
|
|
|
**Install the dependencies with:**
|
|
```
|
|
make install
|
|
```
|
|
|
|
**Build with:**
|
|
```
|
|
make all
|
|
```
|
|
|
|
**Start the server with:**
|
|
```
|
|
./goshort serve
|
|
```
|
|
|
|
## Development
|
|
If you want to develop locally, you'll need:
|
|
- Go 1.21 or greater
|
|
- Node 18 or greater
|
|
|
|
**Install the dependencies with:**
|
|
```
|
|
make install
|
|
```
|
|
|
|
**Start the development server with:**
|
|
```
|
|
make dev
|
|
```
|
|
|
|
This will start the following:
|
|
- Frontend dev server at http://localhost:3000
|
|
- Backend dev server at http://localhost:8080
|
|
|
|
Frontend changes are hot-reloaded, but backend changes require a restart.
|