I am a bit short on time right now, but will try to post it this weekend.
Zurga
serpent
serpent
Got it to work, finally. Little knowledge dump here – still room for improvement. Comes with a little helper script to connect to the running node (if enabled in the module).
heroicons as Mix dep is problematic: 1. comes in via git, 2. is not a Mix package
Moved it to npm as per Phoenix 1.7 with npm · Latinum.
If you don’t want to introduce a Release module, you can also eval app start and repo migration directly in the startup script (or do it manually).
Final package.nix
{
lib,
beamPackages,
nodejs,
makeWrapper,
fetchgit,
buildNpmPackage,
}: let
pname = "senegal-phoenix";
version = "0.1.0";
src = fetchgit {
url = "https://git.example.com/self/senegal-phoenix.git";
rev = "07ec6af047c5df2ed97f3d806070dd4ce1a46fd8";
sha256 = "sha256-id2oxX8a5wgO/AhnZGigZ7AzFBZ+mhTptPeCxlYpOFk=";
};
# Build assets with npm
assets = buildNpmPackage {
pname = "${pname}-assets";
inherit version src;
sourceRoot = "${src.name}/assets";
npmDepsHash = "sha256-D8C4ra2RYbHQdv4lILpnAra0+TBszh+bAW9iqUTfWBQ=";
dontNpmBuild = true;
installPhase = ''
runHook preInstall
cp -r . $out/
runHook postInstall
'';
};
# Fetch Mix dependencies using beamPackages.fetchMixDeps
mixFodDeps = beamPackages.fetchMixDeps {
pname = "${pname}-mix-deps";
inherit src version;
sha256 = "sha256-AzGYVTcESiTVmhDM3lSdg9EWzAe8+aBkerqcwCR2xQY=";
};
in
beamPackages.mixRelease {
inherit pname version src mixFodDeps;
nativeBuildInputs = [
makeWrapper
nodejs
];
# Environment for production build
MIX_ENV = "prod";
# Clean up any existing build artifacts before Nix creates symlinks
preConfigure = ''
rm -rf deps _build assets
'';
# Setup pre-built assets before Mix compile
preBuild = ''
# Copy pre-built assets from npm package
cp --no-preserve=mode -r ${assets} assets
# Fix esbuild executable permissions
chmod +x assets/node_modules/@esbuild/*/bin/esbuild 2>/dev/null || true
chmod +x assets/node_modules/.bin/* 2>/dev/null || true
'';
# Build the release with assets
postBuild = ''
# Deploy Phoenix assets
mix do deps.loadpaths --no-deps-check, assets.deploy
mix do deps.loadpaths --no-deps-check, phx.digest priv/static
'';
# Install and create wrapper
postInstall = ''
# Create a wrapper script for easier execution
mkdir -p $out/bin
makeWrapper $out/bin/senegal $out/bin/senegal-server \
--set MIX_ENV prod \
--set PHX_SERVER true
'';
passthru = {
inherit assets;
};
meta = with lib; {
description = "Phoenix LiveView application packaging example";
homepage = "https://github.com/your-org/senegal-phoenix";
license = licenses.mit;
maintainers = [];
platforms = platforms.unix;
};
}
Final module.nix
{
config,
lib,
pkgs,
...
}: let
cfg = config.services.senegal-phoenix;
senegalPhoenix = pkgs.callPackage ../pkgs/senegal-phoenix.nix {};
in {
options.services.senegal-phoenix = {
enable = lib.mkEnableOption "Senegal Phoenix - Example App";
package = lib.mkOption {
type = lib.types.package;
default = senegalPhoenix;
description = "The Senegal Phoenix package to use";
};
port = lib.mkOption {
type = lib.types.port;
default = 4000;
description = "Port to listen on";
};
host = lib.mkOption {
type = lib.types.str;
default = "localhost";
description = "The host to configure the router generation from";
};
environmentFile = lib.mkOption {
type = lib.types.nullOr lib.types.path;
default = null;
description = ''
Path to environment file containing configuration variables (sourced by systemd).
Example file contents:
DATABASE_URL=postgresql://user:pass@host/db
SECRET_KEY_BASE=your-secret-key-here
# MUST be set
RELEASE_COOKIE=your-erlang-cookie-here
'';
};
secretKeyBaseFile = lib.mkOption {
type = lib.types.nullOr lib.types.path;
default = null;
description = "A file containing the Phoenix Secret Key Base";
};
databaseUrlFile = lib.mkOption {
type = lib.types.nullOr lib.types.path;
default = null;
description = "A file containing the URL to connect to the database";
};
openAIKeyFile = lib.mkOption {
type = lib.types.nullOr lib.types.path;
default = null;
description = "A file containing the OpenAI API key";
};
enableDistribution = lib.mkOption {
type = lib.types.bool;
default = false;
description = ''
Enable Erlang distribution for remote shell access and clustering.
Requires RELEASE_COOKIE to be set in environmentFile for authentication.
Provides 'senegal-connect' command for connecting to the running node.
'';
};
user = lib.mkOption {
type = lib.types.str;
default = "senegal-phoenix";
description = "User account under which the service runs";
};
group = lib.mkOption {
type = lib.types.str;
default = "senegal-phoenix";
description = "Group account under which the service runs";
};
dataDir = lib.mkOption {
type = lib.types.path;
default = "/var/lib/senegal-phoenix";
description = "Directory to store application data";
};
};
config = lib.mkIf cfg.enable {
users.users.${cfg.user} = {
description = "Senegal Phoenix service user";
group = cfg.group;
home = cfg.dataDir;
createHome = true;
isSystemUser = true;
};
users.groups.${cfg.group} = {};
systemd.services.senegal-phoenix = {
description = "Senegal Phoenix - Child sponsorship management system";
after = ["network.target"];
wantedBy = ["multi-user.target"];
serviceConfig = {
Type = "exec";
User = cfg.user;
Group = cfg.group;
WorkingDirectory = cfg.dataDir;
Restart = "on-failure";
RestartSec = "5s";
# Environment file injection
EnvironmentFile = lib.mkIf (cfg.environmentFile != null) cfg.environmentFile;
# Security hardening
NoNewPrivileges = true;
PrivateTmp = true;
ProtectSystem = "strict";
ProtectHome = true;
ReadWritePaths = [cfg.dataDir];
# Load credentials securely
LoadCredential = lib.filter (x: x != null) [
(lib.optionalString (cfg.secretKeyBaseFile != null) "SECRET_KEY_BASE:${cfg.secretKeyBaseFile}")
(lib.optionalString (cfg.databaseUrlFile != null) "DATABASE_URL:${cfg.databaseUrlFile}")
(lib.optionalString (cfg.openAIKeyFile != null) "OPENAI_API_KEY:${cfg.openAIKeyFile}")
];
};
script = let
credentialSetup = ''
# Load individual credential files
${lib.optionalString (cfg.secretKeyBaseFile != null) ''
export SECRET_KEY_BASE="$(< $CREDENTIALS_DIRECTORY/SECRET_KEY_BASE)"
''}
${lib.optionalString (cfg.databaseUrlFile != null) ''
export DATABASE_URL="$(< $CREDENTIALS_DIRECTORY/DATABASE_URL)"
''}
${lib.optionalString (cfg.openAIKeyFile != null) ''
export OPENAI_API_KEY="$(< $CREDENTIALS_DIRECTORY/OPENAI_API_KEY)"
''}
'';
in ''
${credentialSetup}
# Set node name with actual hostname for distribution
${lib.optionalString cfg.enableDistribution ''
export RELEASE_NODE="senegal@$(hostname)"
''}
# Run database migrations
${cfg.package}/bin/senegal eval "Senegal.Release.migrate()"
# Start the Phoenix server
${cfg.package}/bin/senegal-server start
'';
environment = {
# Phoenix configuration
PHX_HOST = cfg.host;
PORT = toString cfg.port;
# Elixir/OTP configuration
RELEASE_DISTRIBUTION =
if cfg.enableDistribution
then "sname"
else "none";
RELEASE_NODE = "senegal@localhost";
# Application-specific defaults
ECTO_IPV6 = "false";
};
};
# Script for connecting to the BEAM node
environment.systemPackages = lib.mkIf cfg.enableDistribution [
(pkgs.writeShellScriptBin "senegal-connect" (let
connectCommand = ''
cd ${cfg.dataDir}
${lib.optionalString (cfg.environmentFile != null) ''
set -a
source ${cfg.environmentFile}
set +a
''}
exec ${cfg.package}/bin/senegal remote
'';
in ''
if [ "$(whoami)" = "${cfg.user}" ]; then
${connectCommand}
elif [ "$(id -u)" = "0" ]; then
exec su -m ${cfg.user} -c "${connectCommand}"
else
echo "Must run as root or ${cfg.user} user. Try: sudo senegal-connect"
exit 1
fi
''))
];
};
}
release.ex
defmodule Senegal.Release do
@moduledoc """
Used for executing DB release tasks when run in production without Mix installed.
"""
@app :senegal
def migrate do
load_app()
for repo <- repos() do
{:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :up, all: true))
end
end
def rollback(repo, version) do
load_app()
{:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))
end
defp repos do
Application.fetch_env!(@app, :ecto_repos)
end
defp load_app do
Application.load(@app)
end
end
Automatic notes (careful, might be inaccurate and not reflect latest changes to above files):
Nix Package Development Notes
Objective
Transform the Senegal Phoenix Elixir/Phoenix application into a Nix package for reproducible builds and deployment.
Approaches Tried
1. beamPackages.fetchMixDeps (Initial Attempt)
Status: Failed due to Git dependency issues
Method:
- Used
beamPackages.fetchMixDepsto fetch all Mix dependencies - Used
beamPackages.mixReleasefor final package creation
Issues Encountered:
- Git Dependencies:
fetchMixDepsdoesn’t handle Git dependencies well - Heroicons Dependency: The heroicons dependency from GitHub caused lock mismatches
- Symlink Errors: Initial “ln: failed to create symbolic link ‘./deps’: File exists” errors
Key Fix:
- Added
preConfigure = ''rm -rf deps _build''to clean build artifacts before Nix creates symlinks - Simplified heroicons dependency in
mix.exsby removingsparse: "optimized"anddepth: 1options
Final Error: Lock mismatch for heroicons Git dependency persisted despite hash updates
2. mix2nix Approach (Current)
Status: In progress, still has dependency lock issues
Method:
- Generate
mix.nixfile usingmix2nixtool - Handle Git dependencies manually (heroicons via
fetchFromGitHub) - Use
mixNixDepsinstead ofmixFodDeps
Implementation:
# Heroicons Git dependency (mix2nix doesn't support Git deps)
heroicons = fetchFromGitHub {
owner = "tailwindlabs";
repo = "heroicons";
rev = "v2.1.1";
hash = "sha256-4yRqfY8r2Ar9Fr45ikD/8jK+H3g4veEHfXa9BorLxXg=";
};
# Mix dependencies from generated mix.nix
mixNixDeps = import ./mix.nix {
inherit lib beamPackages;
};
Current Issues:
- Multiple dependency lock mismatches (finch, openai_ex, websock, bandit, swoosh, etc.)
mix.nixgenerated dependencies don’t matchmix.lockversions- Need
--no-deps-checkflag but still getting validation errors
Key Learnings
Git Dependencies in Nix
beamPackages.fetchMixDepshas poor support for Git dependencies- Git dependencies need manual handling via
fetchFromGitHub - Mix dependency specifications with
sparseanddepthoptions confuse Nix tools
Source Filtering
- Using
src = ./.can include unwanted build artifacts lib.cleanSourcehelps filter but may not be sufficient- Proper
.gitignorepatterns are crucial for clean Nix builds
Mix Lock File Synchronization
- Nix tools expect exact version matches between
mix.lockand generated dependency files - Local development changes to dependencies can break Nix builds
--no-deps-checkflag needed to bypass validation in Nix context
Resources Referenced
- Packaging Elixir Applications with Nix
- Pleroma Package Example
- Nix Union/Exclude Files
- Elixir Forum: Phoenix LiveView with Nix
- Nixpkgs BEAM Documentation
3. beamPackages.fetchMixDeps (Second Attempt - SUCCESS!)
Status: 
SUCCESS! Working Nix package
Key Changes:
- Removed Git Dependencies: Cleaned heroicons Git dependency from mix.lock using
mix deps.clean --unused --unlock - Switched to npm heroicons: Now using heroicons via npm package in assets/package.json instead of Git
- Simplified Asset Handling: Build assets as part of main build process, not separately
- Correct Wrapper Path: Fixed makeWrapper to use correct executable path
Implementation:
# Uses beamPackages.fetchMixDeps for Mix dependencies
mixFodDeps = beamPackages.fetchMixDeps {
pname = "${pname}-mix-deps";
src = lib.cleanSource ./.;
version = version;
sha256 = "sha256-vtNELuwL0S1jyfpAKp+Z/356jf8Jq4Lx9eF69c/EYyI=";
mixEnv = "prod";
};
# Assets built during main build process
preBuild = ''
cd assets
npm install
cd ..
'';
postBuild = ''
mix assets.deploy
'';
Success Factors:
- No Git Dependencies: All dependencies are now from Hex registry
- Clean mix.lock: Regenerated after removing Git dependencies
- npm heroicons: Switched from Git to npm package for heroicons
- Integrated Asset Build: Assets built within Phoenix build context, not separately
0
Zurga
Nice to get it working!
I was doing some refactoring last night to make my script a bit more modular. The progress is on GitHub - Zurga/phoenix_nix · GitHub
2