109 lines
4.4 KiB
Markdown
109 lines
4.4 KiB
Markdown
|
# 🌎 Firefish Developer Docs
|
|||
|
|
|
|||
|
|
## Nix Dev Environment
|
|||
|
|
The Firefish repo comes with a Nix-based shell environment to help make development as easy as possible!
|
|||
|
|
|
|||
|
|
Please note, however, that this environment will not work on Windows outside of a WSL2 environment.
|
|||
|
|
|
|||
|
|
### Prerequisites
|
|||
|
|
|
|||
|
|
- Installed the [Nix Package Manager](https://nixos.org/download.html) (use the comman on their website)
|
|||
|
|
- Installed [direnv](https://direnv.net/docs/installation.html) and added its hook to your shell. (package manager)
|
|||
|
|
|
|||
|
|
Once the repo is cloned to your computer, follow these next few steps inside the Firefish folder:
|
|||
|
|
|
|||
|
|
- Run `direnv allow`. This will build the environment and install all needed tools.
|
|||
|
|
- Run `install-deps`, then `prepare-config`, to install the node dependencies and prepare the needed config files.
|
|||
|
|
- In a second terminal, run `devenv up`. This will spawn a **Redis** server, a **Postgres** server, and the **Firefish** server in dev mode.
|
|||
|
|
- Once you see the Firefish banner printed in your second terminal, run `migrate` in the first.
|
|||
|
|
- Once migrations finish, open http://localhost:3000 in your web browser.
|
|||
|
|
- You should now see the admin user creation screen!
|
|||
|
|
|
|||
|
|
Note: When you want to restart a dev server, all you need to do is run `devenv up`, no other steps are necessary.
|
|||
|
|
|
|||
|
|
# Possible Troubles with the dev enviroment
|
|||
|
|
(this doesn't have to be done under normal conditions, this is for future reference)
|
|||
|
|
|
|||
|
|
### direnv
|
|||
|
|
If you have any trouble with `direnv allow`
|
|||
|
|
Check that the contents of `.envrc` have the same version of nix-direnv that is specified here:
|
|||
|
|
> nix-direnv under -> installation -> using direnv source url
|
|||
|
|
> https://github.com/nix-community/nix-direnv#direnv-source_url
|
|||
|
|
|
|||
|
|
there should be no errors during `direnv allow`
|
|||
|
|
|
|||
|
|
### outdated nix packages
|
|||
|
|
if `install-deps` or any subsequent command doesn't run due to versioning problems
|
|||
|
|
`flake.nix` and `flake.lock` may be outdated
|
|||
|
|
|
|||
|
|
delete `flake.lock`, or better, run `nix flake update --extra-experimental-features flakes --extra-experimental-features nix-command`
|
|||
|
|
after that, run `direnv rebuild`
|
|||
|
|
|
|||
|
|
if there are any errors, you might have to change `flake.nix`
|
|||
|
|
(because the available options can change between versions - consider getting support in [the matrix channel](https://matrix.to/#/#firefish:matrix.fedibird.com))
|
|||
|
|
|
|||
|
|
### after changing a node version
|
|||
|
|
in my case, i had to change the node version from 19, to 18
|
|||
|
|
|
|||
|
|
! before proceeding, make sure to delete all build artifacts!
|
|||
|
|
remove `node_modules` and `built` folders, and maybe `.devenv` and `.direnv` as well
|
|||
|
|
manually, or run `npm cache clean --force` and `pnpm cleanall`
|
|||
|
|
|
|||
|
|
### Windows Subsystem for Linux
|
|||
|
|
if `devenv up` terminates because of wrong folder permissions,
|
|||
|
|
|
|||
|
|
create the file `/etc/wsl.conf` in your distro and add
|
|||
|
|
```shell
|
|||
|
|
[automount]
|
|||
|
|
options = "metadata"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
this allows `chmod` calls to actually have an effect.
|
|||
|
|
the build scripts DO actually set the permissions, it just needs to work in wsl.
|
|||
|
|
|
|||
|
|
### devenv up
|
|||
|
|
devenv up may take a looong time. (some say this is fake news, maybe it was bad luck in my case)
|
|||
|
|
|
|||
|
|
do not get spooked by this error:
|
|||
|
|
```
|
|||
|
|
> firefish@14.0.0-dev32 start /mnt/.../firefish
|
|||
|
|
> pnpm --filter backend run start
|
|||
|
|
|
|||
|
|
|
|||
|
|
> backend@ start /mnt/.../firefish/packages/backend
|
|||
|
|
> pnpm node ./built/index.js
|
|||
|
|
|
|||
|
|
node:internal/modules/cjs/loader:1078
|
|||
|
|
throw err;
|
|||
|
|
^
|
|||
|
|
|
|||
|
|
Error: Cannot find module '/mnt/.../firefish/packages/backend/built/index.js'
|
|||
|
|
at Module._resolveFilename (node:internal/modules/cjs/loader:1075:15)
|
|||
|
|
at Module._load (node:internal/modules/cjs/loader:920:27)
|
|||
|
|
at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
|
|||
|
|
at node:internal/main/run_main_module:23:47 {
|
|||
|
|
code: 'MODULE_NOT_FOUND',
|
|||
|
|
requireStack: []
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
Node.js v18.16.0
|
|||
|
|
undefined
|
|||
|
|
/mnt/.../firefish/packages/backend:
|
|||
|
|
ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL backend@ start: `pnpm node ./built/index.js`
|
|||
|
|
Exit status 1
|
|||
|
|
ELIFECYCLE Command failed with exit code 1.
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
the script is designed to constantly try to start the server, while the build is still running.
|
|||
|
|
this just means that the build isn't finished yet.
|
|||
|
|
|
|||
|
|
at some point you should see a banner that says "Firefish" in big letters -
|
|||
|
|
then you're good to go and can run `migrate` (in another terminal)!
|
|||
|
|
|
|||
|
|
if you don't see the banner,
|
|||
|
|
and it's for some reason stuck on `Finished 'build' after 917 ms` for a view minutes,
|
|||
|
|
|
|||
|
|
just leave devenv running and open another terminal in the folder
|
|||
|
|
run `migrate` and then `pnpm --filter backend run start` by yourself
|
|||
|
|
the server should start
|