forked from mirrors/iceshrimp
[docs] Update nix development docs
Updates them to note you need to install git-lfs Removes parts related to the rust parts of the environment that no longer exist Also adds that if you have problems with the environment, you should join the matrix room and ping me.
This commit is contained in:
Pyrox
Laura Hausmann
parent
e17f2659f5
commit
1b10406474
|
|
@ -1,108 +0,0 @@
|
|||
# 🌎 Iceshrimp Developer Docs
|
||||
|
||||
## Nix Dev Environment
|
||||
The Iceshrimp 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 Iceshrimp 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 **Iceshrimp** server in dev mode.
|
||||
- Once you see the Iceshrimp 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/#/%23iceshrimp-dev:161.rocks))
|
||||
|
||||
### 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:
|
||||
```
|
||||
> iceshrimp@14.0.0-dev32 start /mnt/.../iceshrimp
|
||||
> pnpm --filter backend run start
|
||||
|
||||
|
||||
> backend@ start /mnt/.../iceshrimp/packages/backend
|
||||
> pnpm node ./built/index.js
|
||||
|
||||
node:internal/modules/cjs/loader:1078
|
||||
throw err;
|
||||
^
|
||||
|
||||
Error: Cannot find module '/mnt/.../iceshrimp/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/.../iceshrimp/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 "Iceshrimp" 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
|
||||
42
docs/nix-development.md
Normal file
42
docs/nix-development.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# 🌎 Iceshrimp Developer Docs
|
||||
|
||||
## Nix Dev Environment
|
||||
The Iceshrimp 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)
|
||||
- Ensured all dependencies are pulled with `git-lfs`, which also needs to be installed.
|
||||
|
||||
Once the repo is cloned to your computer, follow these next few steps inside the Iceshrimp 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 **Iceshrimp** server in dev mode.
|
||||
- Once you see the Iceshrimp 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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Problems with the environment
|
||||
|
||||
We don't anticipate any problems with the environment, as it is kept stable and does not require much maintainence.
|
||||
|
||||
Nevertheless, if you do encounter nix-specific problems and are unable to solve these problems yourself, please join the [Matrix support Channel](https://matrix.to/#/%23iceshrimp-dev:161.rocks)
|
||||
and ping @Pyrox with the specific error message you encounter.
|
||||
Loading…
Reference in a new issue