more swagger docs + other changes (#125)

* more swagger docs + other changes

* go fmt

docs/api/swagger.yaml

@@ -1449,6 +1449,203 @@ paths:
       summary: Verify a token by returning account details pertaining to it.
       tags:
       - accounts
+  /api/v1/admin/custom_emojis:
+    post:
+      consumes:
+      - multipart/form-data
+      operationId: emojiCreate
+      parameters:
+      - description: |-
+          The code to use for the emoji, which will be used by instance denizens to select it.
+          This must be unique on the instance.
+        example: blobcat_uwu
+        in: formData
+        name: shortcode
+        pattern: \w{2,30}
+        type: string
+      - description: A jpeg, png, or gif image of the emoji.
+        in: formData
+        name: domains
+        type: file
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: The newly-created emoji.
+          schema:
+            $ref: '#/definitions/emoji'
+        "400":
+          description: bad request
+        "403":
+          description: forbidden
+      security:
+      - OAuth2 Bearer:
+        - admin
+      summary: Upload and create a new instance emoji.
+      tags:
+      - admin
+  /api/v1/admin/domain_blocks:
+    get:
+      operationId: domainBlocksGet
+      parameters:
+      - description: |-
+          If set to true, then each entry in the returned list of domain blocks will only consist of
+          the fields 'domain' and 'public_comment'. This is perfect for when you want to save and share
+          a list of all the domains you have blocked on your instance, so that someone else can easily import them,
+          but you don't need them to see the database IDs of your blocks, or private comments etc.
+        in: query
+        name: export
+        type: boolean
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: All domain blocks currently in place.
+          schema:
+            items:
+              $ref: '#/definitions/domainBlock'
+            type: array
+        "400":
+          description: bad request
+        "403":
+          description: forbidden
+        "404":
+          description: not found
+      security:
+      - OAuth2 Bearer:
+        - admin
+      summary: View all domain blocks currently in place.
+      tags:
+      - admin
+    patch:
+      consumes:
+      - multipart/form-data
+      description: |-
+        Note that you have two options when using this endpoint: either you can set 'import' to true
+        and upload a file containing multiple domain blocks, JSON-formatted, or you can leave import as
+        false, and just add one domain block.
+
+        The format of the json file should be something like: `[{"domain":"example.org"},{"domain":"whatever.com","public_comment":"they smell"}]`
+      operationId: domainBlockCreate
+      parameters:
+      - description: |-
+          Signal that a list of domain blocks is being imported as a file.
+          If set to true, then 'domains' must be present as a JSON-formatted file.
+          If set to false, then 'domains' will be ignored, and 'domain' must be present.
+        in: query
+        name: import
+        type: boolean
+      - description: |-
+          JSON-formatted list of domain blocks to import.
+          This is only used if 'import' is set to true.
+        in: formData
+        name: domains
+        type: file
+      - description: |-
+          Single domain to block.
+          Used only if 'import' is not true.
+        example: example.org
+        in: formData
+        name: domain
+        type: string
+      - description: |-
+          Obfuscate the name of the domain when serving it publicly.
+          Eg., 'example.org' becomes something like 'ex***e.org'.
+          Used only if 'import' is not true.
+        in: formData
+        name: obfuscate
+        type: boolean
+      - description: |-
+          Public comment about this domain block.
+          Will be displayed alongside the domain block if you choose to share blocks.
+          Used only if 'import' is not true.
+        example: harassment, transphobia
+        in: formData
+        name: public_comment
+        type: string
+      - description: |-
+          Private comment about this domain block. Will only be shown to other admins, so this
+          is a useful way of internally keeping track of why a certain domain ended up blocked.
+          Used only if 'import' is not true.
+        example: harassment, transphobia, and some stuff only other admins need to
+          know about
+        in: formData
+        name: private_comment
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: "The newly created domain block, if import != true.\nNote that
+            if a list has been imported, then an `array` of\nnewly created domain
+            blocks will be returned instead. "
+          schema:
+            $ref: '#/definitions/domainBlock'
+        "400":
+          description: bad request
+        "403":
+          description: forbidden
+      security:
+      - OAuth2 Bearer:
+        - admin
+      summary: Create one or more domain blocks, from a string or a file.
+      tags:
+      - admin
+  /api/v1/admin/domain_blocks/{id}:
+    delete:
+      operationId: domainBlockDelete
+      parameters:
+      - description: The id of the domain block.
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: The domain block that was just deleted.
+          schema:
+            $ref: '#/definitions/domainBlock'
+        "400":
+          description: bad request
+        "403":
+          description: forbidden
+        "404":
+          description: not found
+      security:
+      - OAuth2 Bearer:
+        - admin
+      summary: Delete domain block with the given ID.
+      tags:
+      - admin
+    get:
+      operationId: domainBlockGet
+      parameters:
+      - description: The id of the domain block.
+        in: path
+        name: id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: The requested domain block.
+          schema:
+            $ref: '#/definitions/domainBlock'
+        "400":
+          description: bad request
+        "403":
+          description: forbidden
+        "404":
+          description: not found
+      security:
+      - OAuth2 Bearer:
+        - admin
+      summary: View domain block with the given ID.
+      tags:
+      - admin
 schemes:
 - https
 - http

docs/configuration/basics.md

@@ -1 +0,0 @@
-# How to Manage Configuration

docs/configuration/general.md

@@ -1 +1,3 @@
 # General
+
+TODO

docs/configuration/overview.md

@@ -0,0 +1,3 @@
+# Overview
+
+TODO

docs/installation_guide/binary.md

@@ -0,0 +1,3 @@
+# Binary Installation
+
+TODO

docs/installation_guide/docker.md

@@ -1,3 +1,3 @@
 # Docker
 
-Installing with Docker....
+TODO

docs/installation_guide/quick_and_dirty.md

@@ -0,0 +1,127 @@
+# Quick and Dirty
+
+This is the quick and dirty getting started guide. It's not recommended to run GtS like this in production, but if you want to quickly get a server up and running, this is a good way to do it.
+
+## 1: Domain Name
+
+Get a domain name -- [Namecheap](https://www.namecheap.com/) is a good place to do this, but you can use any domain name registrar that lets you manage your own DNS.
+
+## 2: VPS
+
+Spin yourself up a cheap VPS with Linux running on it, or get a homeserver ready with Ubuntu Server or something similar.
+
+[Hostwinds](https://www.hostwinds.com/) is a good option here: it's cheap and they throw in a static IP address for free.
+
+This guide won't go into running [UFW](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-ubuntu-18-04) and [Fail2Ban](https://linuxize.com/post/install-configure-fail2ban-on-ubuntu-20-04/) but you absolutely should do that. Leave ports `443` and `80` open.
+
+## 3: DNS
+
+Point your domain name towards the server you just spun up.
+
+## 4: Postgres
+
+Install [Postgres](https://www.postgresql.org/download/) on your server and run it.
+
+If you have [Docker](https://docs.docker.com/engine/install/ubuntu/) installed on your server, this is as easy as running:
+
+```bash
+docker run -d --network host --user postgres -e POSTGRES_PASSWORD=some_password postgres 
+```
+
+## 5: Build the Binary
+
+On your local machine (not your server), with Go installed, clone the GoToSocial repository, and build the binary with the provided build script:
+
+```bash
+./build.sh
+```
+
+If you need to build for a different architecture other than the one you're running the build on (eg., you're running on a Raspberry Pi but building on an amd64 machine), you can put set `GOOS` or `GOARCH` environment variables before running the build script, eg:
+
+```bash
+GOARCH=arm64 ./build.sh
+```
+
+## 6: Prepare VPS
+
+On the VPS or your homeserver, make the directory that GoToSocial will run from, and the directory it will use as storage:
+
+```bash
+mkdir /gotosocial && mkdir /gotosocial/storage
+```
+
+## 7: Copy Binary
+
+Copy your binary from your local machine onto the VPS, using something like the following command (where `example.org` is the domain you set up in step 1):
+
+```bash
+scp ./gotosocial root@example.org:/gotosocial/gotosocial
+```
+
+Replace `root` with whatever user you're actually running on your remote server (you wouldn't run as root right? ;).
+
+## 8: Copy Web Dir
+
+GoToSocial uses some web templates and static assets, so you need to copy these over to your VPS as well (where `example.org` is the domain you set up in step 1):
+
+```bash
+scp -r ./web root@example.org:/gotosocial/
+```
+
+## 9: Run the Binary
+
+Everything is in place now.
+
+First cd into the directory you created on your remote machine in step 6:
+
+```bash
+cd /gotosocial
+```
+
+Then start the GoToSocial server with the following command (where `example.org` is the domain you set up in step 1, and `some_password` is the password you set for Postgres in step 4):
+
+```bash
+./gotosocial --host example.org --port 443 --storage-serve-host example.org --letsencrypt-enabled=true server start
+```
+
+The server should now start up and you should be able to access the splash page by navigating to your domain in the browser. Note that it might take up to a minute or so for your LetsEncrypt certificates to be created for the first time, so refresh a few times if necessary.
+
+Note that for this example we're assuming that we're allowed to run on port 443 (standard https port), and that nothing else is running on this port.
+
+## 10: Create and confirm your user
+
+You can use the GoToSocial binary to also create, confirm, and promote your user account.
+
+### Create
+
+Run the following command to create a new account:
+
+```bash
+./gotosocial --host example.org admin account create --username some_username --email some_email@whatever.org --password SOME_PASSWORD
+```
+
+In the above command, replace `example.org` with your domain, `some_username` with your desired username, `some_email@whatever.org` with the email address you want to associate with your account, and `SOME_PASSWORD` with a secure password.
+
+### Confirm
+
+Run the following command to confirm the account you just created:
+
+```bash
+./gotosocial --host example.org admin account confirm --username some_username
+```
+
+Replace `example.org` with your domain and `some_username` with the username of the account you just created.
+
+### Promote
+
+If you want your user to have admin rights, you can promote them using a similar command:
+
+```bash
+./gotosocial --host example.org admin account promote --username some_username
+```
+
+Replace `example.org` with your domain and `some_username` with the username of the account you just created.
+
+## 11. Login!
+
+You should now be able to log in to your instance using the email address and password of the account you just created. We recommend using [Pinafore](https://pinafore.social) or Tusky for this.