git.squeep.com Git - akkoma/blob - docs/docs/development/setting_up_akkoma_dev.md

   1 # Setting up a Akkoma development environment
   2
   3 Akkoma requires some adjustments from the defaults for running the instance locally. The following should help you to get started.
   4
   5 ## Installing
   6
   7 1. Install Akkoma as explained in [the docs](../installation/debian_based_en.md), with some exceptions:
   8     * No need to create a dedicated akkoma user, it's easier to just use your own user
   9     * You can use your own fork of the repository and add akkoma as a remote `git remote add akkoma 'https://akkoma.dev/AkkomaGang/akkoma.git'`
  10     * For domain you can use `localhost`
  11     * For the DB you can still choose a dedicated user. The mix tasks sets it up, so it's no extra work for you
  12     * instead of creating a `prod.secret.exs`, create `dev.secret.exs`
  13     * No need to prefix with `MIX_ENV=prod`. We're using dev and that's the default MIX_ENV
  14     * You can skip nginx and systemd
  15     * For front-end, you'll probably want to install and use the develop branch instead of the stable branch. There's no guarantee that the stable branch of the FE will always work on the develop branch of the BE.
  16 2. Change the dev.secret.exs
  17     * Change the FE settings to use the installed branch (see also [Frontend Management](/configuration/frontend_management/))
  18     * Change the scheme in `config :pleroma, Pleroma.Web.Endpoint` to http (see examples below)
  19     * If you want to change other settings, you can do that too
  20 3. You can now start the server with `mix phx.server`. Once it's build and started, you can access the instance on `http://<host>:<port>` (e.g.http://localhost:4000 ) and should be able to do everything locally you normally can.
  21
  22 Example on how to install pleroma-fe and admin-fe using it's develop branch
  23 ```sh
  24 mix pleroma.frontend install pleroma-fe --ref develop
  25 mix pleroma.frontend install admin-fe --ref develop
  26 ```
  27
  28 Example config to use the pleroma-fe and admin-fe installed from the develop branch
  29 ```elixir
  30 config :pleroma, :frontends,
  31   primary: %{"name" => "pleroma-fe", "ref" => "develop"},
  32   admin: %{"name" => "admin-fe", "ref" => "develop"}
  33 ```
  34
  35 Example config to change the scheme to http. Change the port if you want to run on another port.
  36 ```elixir
  37 config :pleroma, Pleroma.Web.Endpoint,
  38   url: [host: "localhost", scheme: "http", port: 4000],
  39 ```
  40
  41 Example config to disable captcha. This makes it a bit easier to create test-users.
  42 ```elixir
  43 config :pleroma, Pleroma.Captcha,
  44   enabled: false
  45 ```
  46
  47 Example config to change the log level to info
  48 ```elixir
  49 config :logger, :console,
  50   # :debug :info :warning :error
  51   level: :info
  52 ```
  53
  54 ## Testing with HTTPS
  55
  56 If you end up developing alongside other software like misskey,
  57 you will not be able to federate without an SSL certificate. You should
  58 be able to use the snakeoil certificate that comes standard with most
  59 distributions or generate one from scratch, then force elixir to accept it.
  60
  61 HTTP clients are none too keen to accept self-signed certs, but we can do
  62 this:
  63
  64 ```elixir
  65 config :pleroma, :http,
  66   adapter: [
  67     pools: %{
  68       default: [
  69         conn_opts: [
  70           transport_opts: [
  71             verify: :verify_none
  72           ]
  73         ]
  74       ]
  75     }
  76   ]
  77 ```
  78
  79 Now your SSL requests will work. Hooray.
  80
  81 ## Testing
  82
  83 1. Create a `test.secret.exs` file with the content as shown below
  84 2. Create the database user and test database.
  85     1. You can use the `config/setup_db.psql` as a template. Copy the file if you want and change the database name, user and password to the values for the test-database (e.g. 'akkoma_local_test' for database and user). Then run this file like you did during installation.
  86     2. The tests will try to create the Database, so we'll have to allow our test-database user to create databases, `sudo -Hu postgres psql -c "ALTER USER akkoma_local_test WITH CREATEDB;"`
  87 3. Run the tests with `mix test`. The tests should succeed.
  88
  89 Example content for the `test.secret.exs` file. Feel free to use another user, database name or password, just make sure the database is dedicated for the testing environment.
  90 ```elixir
  91 # Akkoma test configuration
  92
  93 # NOTE: This file should not be committed to a repo or otherwise made public
  94 # without removing sensitive information.
  95
  96 import Config
  97
  98 config :pleroma, Pleroma.Repo,
  99   username: "akkoma_local_test",
 100   password: "mysuperduperpassword",
 101   database: "akkoma_local_test",
 102   hostname: "localhost"
 103
 104 ```
 105
 106 ## Updating
 107
 108 Update Akkoma as explained in [the docs](../administration/updating.md). Just make sure you pull from upstream and not from your own fork.
 109
 110 ## Working on multiple branches
 111
 112 If you develop on a separate branch, it's possible you did migrations that aren't merged into another branch you're working on. In that case, it's probably best to set up multiple Akkoma instances each with their own database. If you finished with a branch and want to switch back to develop to start a new branch from there, you can drop the database and recreate the database (e.g. by using `config/setup_db.psql`). The commands to drop and recreate the database can be found in [the docs](../administration/backup.md).