Spacebin - Text sharing for the final frontier

Welcome to the official Spacebin wiki.

This wiki contains a lot of useful information on Spacebin, all of which is listed on the Sidebar.

What is Spacebin?

Spacebin is a highly-reliable pastebin server, built with Golang and Fiber, that's capable of serving notes, documents, code or any other form of text!

How Spacebin works

When you send a document to a Spacebin server the server generates a unique key for that document and makes the document available to any client accessing the server via the unique key.

A client can now ask the server for the document by using it's unique key. If the request is performed correctly the server will respond with the document. The client will now display the document's content.

Contributing

If you'd like, you can contribute to the Wiki on Github, View the repository here.

Chapter 01 — Guides

This chapter provides various guides on how to use or a maintain a Spacebin instance.

Spirit Instance Setup

This guide details the very easy process of setting up a Spacebin server instance.

This is a quick guide on how to setup a basic Spacebin API instance.

There are two methods for installing the Spacebin Spirit server:

Docker (recommended)

Prerequisites:

Docker
sudo
An internet connection.

1. Pull and run the Docker image

Using this method the installation and execution of a Spirit instance is quite easy, and can be done with two commands:

# This will pull and run Docker image on Port 80
$ sudo docker pull spacebinorg/spirit:v0.1.6a
$ sudo docker run -d -p 80:9000 spacebinorg/spirit:v0.1.6a

You're done. If you want to configure the Instance you're going to have use a somewhat-convoluted method due to a parsing issue.

You need to use a Docker volume to replace the /opt/spirit/config.toml with a local file containing your instance's configuration. For more information on how to configure consult the Config Options page of this wiki or the Configuring Spirit section on this page.

Manual

Golang
Magefile
An internet connection.
Git

1. Download the Git repository

These two commands will download the Git repository from Github and change into that directory.

$ git clone https://github.com/spacebin-org/spirit.git
$ cd spirit

2. Configure Spirit

You now need to configure your Spirit instance, so that it may run with settings that work best in your environment.

A full list of the options available in the config.toml file are listed on the Config Options page. Each setting comes with a default that we at the Spacebin Team find reasonable.

We're working on creating more in-depth instructions for configuring an instance, but until then you'll have to do with this. Although, we don't think it's very hard to configure Spirit.

There are currently two options you may use for configuring — environment-based and file-based. However, the only one of these options that currently works is the file-based approach as the other approach currently has a known issue with parsing some _ delimited fields.

3. Build and run the binary

Now, you can try building the actual Spirit program. Since the application is written in Go, for any non-production environment we must build a binary for the program.

Thanks to our existing build system this can we be quite easily done, provided you've installed and setup Magefile.

If you have, run the commands either mage run or mage build. Either of these commands will build the Spirit program, however with the former option Mage will automatically run the binary after building it.

If you used instead the latter option you must now execute the spirit binary outputted by the program in the bin/ folder of the project. Since each operating system has a different way of running the binary this guide will not go into depth on how to it should be ran.

Pulsar Setup

This guide details the very easy process of setting up an instance of the Pulsar client for Spacebin.

This is a quick guide on how to install and setup an instance of Spacebin's official web client: Pulsar.

There are two methods for installing Pulsar:

Docker (recommended)

Prerequisites:

Docker
sudo
An internet connection.

1. Pull and run the Docker image

Using this method the installation and execution of a Spirit instance is quite easy, and can be done with two commands:

# This will pull and run Docker image on Port 80
$ sudo docker pull spacebinorg/pulsar:v1.1.3
$ sudo docker run -d \
  --restart=always \
  --env PULSAR_INSTANCE="https://spaceb.in/" \
  -p 3000:80 \
  spacebinorg/pulsar:v1.1.3

You're done. Pulsar doesn't really have a configuration system, just a few environment variables, they are PORT and PULSAR_INSTANCE.

Right now, the PULSAR_INSTANCE environment variable is the only required one and is used to set the Spirit instance which Pulsar will serve as the client for.

Manual

Instructions unfinished.

This section contains lots of information surrounding specifically Spacebin API instances.

Spacebin Server Configuration Options

`server`

server.host: Host address to serve on (default: "127.0.0.1").
server.port: Port number to serve on (default: 9000).
server.use_csp: Whether or not to send a CSP header along with responses (default: true).
server.compress_level: The level of compression to apply to responses. For more information see the Fiber documentation (default: 1).
server.prefork: Whether or not the server should run across multiple processes (default: false).

`server.ratelimits`

server.ratelimits.requests: How many requests to allow per duration (default: 80).
server.ratelimits.duration: How many milliseconds until the rate limit is lifted. (default: 60_000).

`database`

database.dialect: The kind of database to connect to. Possible values are mysql, sqlite, or postgresql (default: "sqlite").
database.connection_uri: The location of the database to connect to (default: "./spacebin.db"). NOTE: When connecting to MySQL databases you must pass the parseTime=True option.

`documents`

documents.id_length: The length of identifiers to generate for documents (default: 8).
documents.max_document_length: The maximum amount of bytes a document can be (default: 400_000).
documents.max_age: The amount of days documents are stored in the database before they're auto-deleted (default: 90).

Example configuration

An example configuration is already provided in the Spacebin Spirit repository. It is repeated here for convenience.

[server]
host = "127.0.0.1"
port = 9000
use_csp = true
compress_level = 1
prefork = false

[server.ratelimits]
requests = 80
duration = 60_000 # in ms

[database]
dialect = "sqlite"
connection_uri = "spacebin.db"

[documents]
id_length = 12
max_document_length = 400_000
max_age = 90 # in days

Endpoint Documentation

Every endpoint on a standard instance is prefixed by /api/v1.

All JSON responses on a standard instance follow a common format and are snake_cased.

On spaceb.in —the Spacebin official instance—, API routes are available at spaceb.in/api/v1 (including prefix).

Responses which only return plain text follow no enforced format and can contain any values. When a request body is present in documentation, it is more often than not JSON.

The format:

{
  "status": 000, // HTTP status code.
  "payload": {
    // The response's content, is an empty object if an error is present.
    ...
  },
  "error": "" // Error message.
}

POST `/documents/`

Request

{
  "content": "...", // The document's content.
  "extension": "...", // The document's file type/extension.
}

Content field

The value of the content field corresponds to the value of the paste and is required in all requests.

Additionally, instances set a max length for this value. By default and on spaceb.in the max length is set to 400,000 bytes or ~390KB. Contact your instance's administrator or consult it's documentation to find the value of the max length of documents on it.

Extension Field

The extension field is used to set the file type of the paste and is required in all requests. Since this field will often be used for syntax highlighting purposes it is important that the value passed accurately corresponds to the format of the text in the file.

The value of this field must follow a specific value, that being one of the following:

python
javascript, jsx
typescript, tsx
go
kotlin
cpp, csharp, c, objc
sql
scala
haskell
shell-session
bash
powershell
php
asm6502
julia
perl
crystal
json, yaml, toml
rust
ruby
java
markdown
markup (Catch-all for html, xml, svg, atom, rss, mathml, ssml)
css

Additionally, a value of none may be used for any paste that does not have/want an extension.

Response

{
  "status": 201,
  "payload": {
    "id": "...", // The unique ID of the document.
    "content_hash": "...", // A base64 representation of the document's content. Useful for content validation.
  },
  "error": ""
}

GET `/documents/:id/`

Request

:id: The document's unique ID.

Response

{
  "status": 201,
  "payload": {
    "id": "...", // The document's unique ID.
    "content": "...", // The document's content.
    "extension": "...", // The document's file type/extension.
    "created_at": 0000000000, // The UNIX timestamp at the time the document was created.
    "updated_at": 0000000000 // The UNIX timestamp at the time the document was last updated, usually the same as `created_at`.
  },
  "error": ""
}

GET `/documents/:id/raw`

Request

:id: The document's unique ID.

Response

The response of this endpoint is just the plain text content of the document. If an error occurs while retrieving the document a JSON response will be sent back instead with the error field populated.

Public Instances

If you have an instance you'd like listed here, please contact the Team via our Discord and we'll try to get back to you in a timely matter!

`spaceb.in`

This is the main public instance and is maintained by the Spacebin team.

This instance is hosted on Juno Hosting's infrastructure in Sacramento, California, United States. Consequently you must conform to all American laws, and all of Juno Hosting's policies.

All data violating these laws/policies will be swiftly removed from our services after being reported.

Service Rules

The rules of the service are as follows:

No illegal, harmful, offensive, or fraudulent content.
No copyrighted content or content that misappropriates the intellectual property of others.
No viruses/malware/computer harming things.
No jail bait.

Additionally, you of course need to follow any and all laws pertaining to the service host in the United States of America and any pertaining to you and your home nation.

Contacting

This instance is operated solely by the Spacebin team. Currently we do not have a team email, so if you need to contact us please email [email protected] (Faster for takedowns.) or [email protected].

Other notes

All data runs through Cloudflare.
This service is rate-limited. If you exceed 500 requests in 1 minute you will be blocked from using the service until 1 minute passes.
Uptime is not guaranteed, we do however make it a goal to keep this instance as stable as possible.
To access the API use the api route (spaceb.in/api/v1/).

Clients & Libraries

This is a list of official and officially recognized clients and API libraries for use with Spacebin.

Not all of these clients are developed by the Spacebin Team, any library/client that is will have the author Spacebin Team and will be marked as official.

Clients

Author	Name	Official?	Platforms	Description	Source
Spacebin Team	`comet`	Yes	`linux`, `win32`, `macOS`, `*bsd`	Fast and recommended terminal client built in Go.	View
Spacebin Team	`pulsar`	Yes	`web`	Official web client for Spacebin.	View
GreatGodApollo	`lunar`	No	`linux`, `win32`, `macOS`, `*bsd`	Alternative CLI for Spacebin in Go.	View
GreatGodApollo	`Spacebin-ComputerCraft`	No	`computercraft`		View
PeachMaster	`Spacebin-OpenComputers`	No	`opencomputers`	A Spacebin Client for OpenComputers.	View

Libraries

Author	Name	Official?	Languages	Description	Source
GreatGodApollo	`gospacebin`	No	`golang`	Golang package for Spacebin API	View

Chapter 03 — CLI Documentation

This section covers the official CLI of Spacebin: Comet. Since development on Comet has not yet begun, documentation on the project has not yet been written and this section is empty.

If you're looking for a CLI to use, you might look over the Clients and Libraries section of this wiki and try one listed there.

Spacebin Wiki