spectura

README

= Spectura

Spectura is a microservice for taking screenshots of websites in an Open Graph
compatible format usable for link previews on sites such as Facebook and
LinkedIn.

Spectura takes a `url` and an optional signature `s` as query parameters. The
signature ensures that we only visit pre-approved URLs.

== Setup

You either need to run a Decap instance manually, or run everything inside
Docker as described xref:run_docker[below].

To run Spectura in Docker, you need Docker version 20.10 or higher.

== Running

=== Basic usage

Assuming that Decap is listening on `localhost:4531`:

[source,shell]
----
go build
USE_SIGNATURES=false ./spectura
----

Then make a GET request on the same host:

[source,shell]
----
curl "http://localhost:19165/api/spectura/v0/screenshot/?url=https://www.jobindex.dk/?pictura=1" --output screenshot.png
----

=== Inside Docker [[run_docker]]

To run Spectura

[NOTE]
Always run with `--build`

[source,shell]
----
docker compose up --build
----

To test Spectura with `curl`

[source,shell]
----
curl 'http://localhost:8080/api/spectura/v0/screenshot?url=https://pyjam.as&expire=1661810399&'
----

If you use kitty terminal you can print the image directly in your terminal
[source,shell]
----
curl 'http://localhost:8080/api/spectura/v0/screenshot?&url=https://pyjam.as&expire=1661810399&' | kitty +kitten icat
----

== Configuration

* `DECAP_URL`, optional, default: `http://localhost:4531`
* `USE_SIGNATURES`, optional, default: `true`
* `SIGNING_SECRET`, required if `USE_SIGNATURES`
* `SIGNING_KEY`, required if `USE_SIGNATURES`
* `SIGNING_UNIQUE_NAME`, optional, default: `jix_spectura`
* `CACHE_TTL`, optional, default: `48h`
* `MAX_IMAGE_SIZE_MIB`, optional, default: `20`