avatars-api/README.md

# Avatars API

A self-hosted avatars API using some of the [DiceBear](https://www.dicebear.com/) CC0 styles

You can take a look at my own self-hosted version here: https://avatars.jusemon.com

The following endpoints are available:

- https://avatars.jusemon.com/list
- https://avatars.jusemon.com/random
- https://avatars.jusemon.com/:seed

The size and style of the image can be changed with the following query params:

- `size`: any number between `16` and `512`
- `style`: see the list endpoint, the valid values are defined by the property `key`

## Example:

https://avatars.jusemon.com/jusemon?size=256&style=open-peeps where jusemon is the :seed

![Example](https://avatars.jusemon.com/jusemon?size=256&style=open-peeps)

## Installation

### Development

For run locally it needs a `.env` file with the environment variables defined in the `.env.example`

ALLOWED_ORIGINS includes a comma separated list for the allowed CORS sites.

Install dependencies `npm install` or `yarn`
To start the project run `npm run dev` or `yarn dev`

### Production

For run it in docker just run `docker compose up`

Alternatively, you can run the image without cloning this repo using the image published [here](https://git.jusemon.com/jusemon/avatars-api/packages)

With docker run:

```sh
docker run -p 3000:3000 -e NODE_ENV=production -e HOST=0.0.0.0 -e PORT=3000 -e API_VERSION=1 -e ALLOWED_ORIGINS=https://example.com git.jusemon.com/jusemon/avatars-api:1.0.0
```

With docker compose:

```yaml
name: avatars
services:
  api:
    image: git.jusemon.com/jusemon/avatars-api:1.0.0
    ports:
      - 3000:3000
    environment:
      NODE_ENV: "production"
      HOST: "0.0.0.0"
      PORT: 3000
      API_VERSION: 1
      ALLOWED_ORIGINS: "https://example.com"
```

## Libraries Used

- DiceBear (for avatar generation)
- sharp (for png exportation)
- uuid (for random seeds)

## Credits

- Created by Juan Sebastián Montoya

### Credits for Styles:

| Title      | Creator       | Source                                                   | Homepage                         | License |
| ---------- | ------------- | -------------------------------------------------------- | -------------------------------- | ------- |
| Open Peeps | Pablo Stanley | https://www.openpeeps.com/                               | https://twitter.com/pablostanley | CC0 1.0 |
| Pixel Art  | DiceBear      | https://www.figma.com/community/file/1198754108850888330 | https://www.dicebear.com         | CC0 1.0 |
| Thumbs     | DiceBear      | https://www.dicebear.com                                 | https://www.dicebear.com         | CC0 1.0 |

## License

This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).