63 lines
4.9 KiB
Markdown
63 lines
4.9 KiB
Markdown
# Sukaato
|
|
|
|
|
|
|
|
This repository is to define a backend for, and to serve, my website. The code here is building upon the basis of a project structure and associated source code supplied by the [Elxir](https://elixir-lang.org/) [Phoenix](https://hexdocs.pm/phoenix/installation.html) web framework package(s)/module(s) and the associated CLI utilities.
|
|
|
|
This project is a WIP.
|
|
|
|
## Execution and installation
|
|
|
|
There are a collection of procedures to follow for proper execution and installation of this server and its website. This is a highly abstract, simplified summary of the execution and installation processes. The plan is to provide more detailed exposition and more precise articulation of the execution and installation processes as the project itself is developed, as some other packages, software tools, or scripts that may be introduced may change the needed detail or precision herein. Some design approaches, structure specifications, and so on, may also have yet to be finalized.
|
|
|
|
### Prerequisitess for Execution or Installation
|
|
|
|
#### Configure `site.toml`
|
|
|
|
Make sure to configure things like the website's name, author, etc., via the `${project_root}/site.toml` file.
|
|
|
|
#### Supplying Resources to Themes
|
|
|
|
Make sure that subdirectories under path `${project_root}/priv/static/` are appropriately populated. Either follow the active/enabled theme's CSS/SASS path references, or change such path references to match custom `${project_root}/priv/static` prefixed filepaths.
|
|
|
|
> [!TIP]
|
|
> Website theme can be changed by assigning a value to `theme` in `${project_root}/site.toml`.
|
|
|
|
References to paths in CSS/SASS file should be absolute paths, insofar as their root is kwown and is `${project_root}/priv/static`. That is, they are relative to the aforementioned path, but not relative to the CSS/SASS file being currently edited.
|
|
|
|
> [!WARNING]
|
|
> The paths referenced in CSS/SASS files recursively under `${project_root}/assets/sass/` or `${project_root}/assets/css/` are relative to `${project_root}/priv/static` and not each CSS/SASS file currently being edited. This is UNLESS subdirectories of `${project_root}/priv/static/` [have not been marked as external in `${project_root}/config/config.exs`](https://hexdocs.pm/phoenix/asset_management.html#images-fonts-and-external-files); in that case, the given filepaths will never be found anyway.
|
|
|
|
SASS files can be found under path `${project_root}/assets/sass/themes/**/`, while CSS files can be found under path `${project_root}/assets/css/`.
|
|
|
|
> [!TIP]
|
|
> Avoid editing file `app.css` under `${project_root}/assets/css/` path directly. Edit SASS files under `${project_root}/assets/sass/themes/${theme_name}/` wherein `$theme_name` corresponds to name of enabled/active website theme. The aforementioned `app.css` file should be the final output starting from the preprocessing of SASS files recursively found under any subdirectory at `${project_root}/assets/sass/themes/`. Which subdirectory's SASS files are to be preprocessed as CSS is based on the relative imports in a symbolic link, `app.sass`, directly under `${project_root}/assets/sass/themes/`. This symbolic link should be to an `export.sass` file found directly under `${project_root}/assets/sass/themes/${theme_name}/` corresponding to the active/enabled website theme.
|
|
|
|
The website has a default theme supplied, but you are welcome to make your own and then set it in `${project_root}/site.toml`.
|
|
|
|
> [!TIP]
|
|
> Make sure that all renderable stylesheet paths for files under `${project_root}/lib/sukaato_web/controllers/page_*` are set to `/assets/app.css`, or a path relative to `${project_root}/priv/static` that has been made external (whether the directory exists yet or not). Again, see about [asset management in Phoenix web framework](https://hexdocs.pm/phoenix/asset_management.html#images-fonts-and-external-files).
|
|
|
|
### Running this project's server
|
|
|
|
This project was built using the Phoenix web framework. To start the Phoenix server:
|
|
|
|
* Place SSL/TLS certificates in/under path `/priv/cert`
|
|
* Make sure `config.exs`, `dev.exs`, or `prod.exs` [reflect the paths to these certificates](https://hexdocs.pm/phoenix/using_ssl.html)
|
|
* Run `mix setup` while at project root to install and setup dependencies
|
|
* Start Phoenix endpoint while at project root with `mix phx.server` or inside IEx with `iex -S mix phx.server`
|
|
|
|
Now you can visit [`localhost:4001`](https://localhost:4001) from your browser.
|
|
|
|
### Running this project in production
|
|
|
|
Ready to run in production? Please [check Phoenix web framework's deployment guides](https://hexdocs.pm/phoenix/deployment.html).
|
|
|
|
## Learn more
|
|
|
|
* [More on the Phoenix web framework](https://www.phoenixframework.org/)
|
|
* [Phoenix web framework guide](https://hexdocs.pm/phoenix/overview.html)
|
|
* [Phoenix web framework documentation](https://hexdocs.pm/phoenix)
|
|
* [Phoenix web framework forum](https://elixirforum.com/c/phoenix-forum)
|
|
* [Phoenix web framework source repository](https://github.com/phoenixframework/phoenix)
|